Фото Yancy Min на Unsplash
Kubernetes — большой проект. Не только потому, что очень востребован, но и с точки зрения исходного кода. На момент написания этой статьи насчитывалось более 86 000 коммитов, более 2000 участников, более 2000 открытых тикетов, более 1000 открытых пул-реквестов и 62 800 звёзд в репозитории на GitHub.
Утилита scc насчитала более 4,3 млн строк кода на Go (всего более 5,2 млн строк), из них более 3 млн строк реального кода и более 700 тыс. строк с комментариями, в общей сложности более 16 000 файлов, включая директорию
vendor/.Недавно мы разработали инструмент, который обрабатывает комментарии TODO в кодовой базе, чтобы помочь в поддержке таких больших проектов.
Мы решили натравить наш маленький парсер на исходники Kubernetes — и посмотреть, что получится. Вот некоторые результаты.
tickgit обработал исходный код из коммита 9bf52c2. Выдача в формате CSV затем была импортирована в SQLite для обработки запросов. Обратите внимание, что инструмент находит TODO только в извлечённом дереве. Он не учитывает комментарии, которые были добавлены и впоследствии удалены. Таким образом, числа отражают только TODO, которые всё ещё «живут» в коде на момент данного коммита.Итого (для 9bf52c2)
- 2380 TODO в 1230 файлах от 363 авторов
- 460 TODO с назначенным исполнителем, например,
// TODO (patrickdevivo) Fix the ...
- 489 TODO добавлены в 2019 году
- Средний возраст TODO — 860 дней (или 2,3 года)
- Самый старый TODO — от 6 июня 2014 года (из «первого коммита»)
- Последний TODO от 9 декабря 2019 года (на момент написания статьи)
- В этом файле больше всего TODO: 33
- deads2k добавил больше всего TODO (git blame): 147
- Этот коммит внёс больше всего TODO, которые до сих пор в исходниках: 64
Результаты
Файлы с наибольшим количеством TODO
33 cluster/gce/util.sh 25 pkg/apis/core/types.go 23 staging/src/k8s.io/api/core/v1/types.go 21 staging/src/k8s.io/legacy-cloud-providers/aws/aws.go 20 staging/src/k8s.io/code-generator/cmd/conversion-gen/generators/conversion.go 20 pkg/apis/core/validation/validation.go 16 test/e2e/network/service.go 16 pkg/kubelet/kubelet.go 14 test/e2e/framework/util.go 14 pkg/kubelet/kubelet_pods.go
Топ авторов по количеству TODO
deads2k 147 Clayton Coleman 105 Chao Xu 99 Dr. Stefan Schimanski 93 Jordan Liggitt 81 David Eads 60 Random-Liu 54 Wojciech Tyczynski 50 Yu-Ju Hong 43 Prashanth Balasubramanian 38
Коммиты, которые внесли максимальное количество TODO (указаны количество TODO и хэш коммита)
64 6a4d5cd7cc58e28c20ca133dab7b0e9e56192fe3 19 e01ff1641c7321ac81fe5775f6ccb21aa6775c04 19 4fb28dafad121e163fa86dc90067ce3d14415811 18 adb75e1fd17b11e6a0256a4984ef9b18957d94ce 14 963c85e1c807efcdbb82dd44439dc3c55f6a0bfd 14 8b17db7e0c4431cd5fd9a5d9a3ab11b04e2f0a7e 13 f0f78299348afcf770d4e8d89dcea82f80811b28 11 d0b94538b9744d0c06df6ddec2604be168568f9d 10 f1248b9c829e225138ab6d6234221c63092f7592 10 cd663d7ad00937cffa8a09e4761acb95d34c89a3
Количество новых TODO по годам
34 2014 249 2015 523 2016 650 2017 435 2018 489 2019
Чтобы воспроизвести результаты, извлеките данные о TODO такой командой:
tickgit todos --csv-output. Результаты выше получены запросами к базе SQLite.Выводы и вопросы
Это довольно поверхностный взгляд на комментарии TODO в исходном коде Kubernetes. Мы видим самых активных «постановщиков заданий», которые более-менее совпадают с ведущими контрибуторами проекта.
Мы также видим, что отношение к комментариям TODO не отличается от нормы, просто из-за большого размера кодовой базы их тоже много.
Важное наблюдение, что комментариев TODO больше, чем тикетов Github (issues). Это интересно, поскольку указывает на значительное количество «скрытых» заданий, которые сразу не видны на GitHub, а прописаны в исходном коде.
Вероятно, основные контрибуторы хорошо разбираются в своих областях кодовой базы и чётко представляют количество собственных TODO и «скрытой работы». Но это не всегда заметно для внешних наблюдателей. Им привычнее и понятнее видеть тикеты на GitHub (или в других общедоступных трекерах).
Большинство разработчиков понимает, что программные проекты «живут и дышат». Происходят частые изменения, процесс совершенствования, исправление ошибок и множество дискуссий. Очень важно хорошо организовать рабочий процесс, потому что хороший код требует постоянных размышлений. Частично мы видим это в действии через комментарии TODO в исходниках Kubernetes. Хотя нам не с чем сравнивать, но средний возраст заданий 2,3 года кажется довольно высоким. Близкие к проекту разработчики могут более объективно оценить этот показатель. Интересно сравнить его с другими крупными опенсорсными проектами.
Более глубокий анализ включил бы все TODO в истории, а не только те, что остались в настоящее время. Можно рассмотреть следующие вопросы:
- С какой скоростью закрываются TODO?
- Какова средняя продолжительность жизни комментария TODO?
- Как выглядят популярные кодовые базы в сравнении?
Насколько это важно?
Комментарии TODO обычно охватывают такой тип работы, который слишком мал для тикета, но достаточно важен, чтобы его отметить и описать в комментарии (хотя многие ссылаются на тикеты/issue). Поскольку комментарии — это часть кода, они часто «ближе» к работе, которую необходимо выполнить. Их легко добавить, но, похоже, так же легко забыть (в исходниках Kubernetes по-прежнему более 1800 TODO, добавленных до 2019 года).
Надеемся, что наш инструмент для анализа метаданных в коде поможет разработчикам обслуживать проекты любого размера. Поднять на поверхность комментарии TODO — это только часть того, что нужно сделать.
