Каждая строка кода должна быть задокументирована

5788

Рассказывает Мислав Мароник, автор блога mislav.uniqpath.com

На данный момент этот блок не поддерживается, но мы не забыли о нём!Наша команда уже занята его разработкой, он будет доступен в ближайшее время.

Каждая строка кода должна быть задокументирована, пускай даже не в виде комментариев. Кто бы ни написал четыре строки ниже, он по какой-то причине захотел получить доступ к свойству clientLeft DOM-узла, но не сделал ничего с результатом. Загадочно, не так ли? Можете ли вы сказать, зачем он сделал это, безопасно ли убирать или изменять этот кусок кода в будущем?

			// ...
if (duration > 0) this.bind(endEvent, wrappedCallback)
this.get(0).clientLeft
this.css(cssValues)

Если кто-то скопировал и показал вам этот код, как я сейчас, вы, скорее всего, не сможете определить, кто написал эти строки, с какой причиной и необходимы ли будут они и дальше. Тем не менее, как правило, когда вы работаете с каким-либо проектом, у вас есть доступ к его истории с помощью системы контроля версий.

История проекта — его самая ценная документация

Тайну можно раскрыть, посмотрев на комментарий коммита, который изменил эту строку:

			$ git show $(git blame example.js -L 4,4 | awk '{print $1}')

Как оказалось, эта строка, а если быть точным, то изменение, которое привело к ней, обладает отличной документацией, которая рассказывает, зачем этот коммит был необходим, почему предыдущий подход оказался неэффективным, какие браузеры были затронуты багом, а также содержит ссылку для дальнейшего чтения.

Кроме того, выяснилось, что автором этой строки был я. Конечно, я мог написать код лучше: например, инкапсулировать получение свойства в функцию с говорящим именем вроде triggerLayout(), или просто добавить комментарий, зачем здесь вообще нужна эта команда. Тем не менее, в тот день я этого не сделал. Код случается, и он не всегда идеален.

Но даже если код объясняет сам себя или в нем есть комментарии, история проекта может предоставить гораздо больше информации:

Кто добавил этот код.
Когда был добавлен этот код.
Как тестировался этот код (если тестировался вообще).
Документация коммита может быть размером с небольшой роман, в то время как комментарии к коду должны быть максимально короткими.

Да, качество очень важно. Но если вы думаете, как можно улучшить ваш код еще больше, то вам стоит обратить внимание на написание подробных объяснений к коммитам. Стоит требовать это не только от себя, но и от всей вашей команды. Документированная история проекта важна не меньше, чем его отладка.

Исследование истории проекта

git blame

Я уже показывал выше, для чего нужна команда git blame. Даже если у вас нет доступа к репозиторию, вы можете ее использовать, чтобы просмотреть историю любого файла на GitHub.

Особенно удобно это делать с помощью Vim и плагина Fugitive для него:

Введите :Gblame в буфере, чтобы открыть просмотр истории.
Если вам нужно углубиться дальше, нажмите Shift+P, чтобы просмотреть историю родителя коммита.
Нажмите О, чтобы открыть двухпанельный вид и посмотреть выбранный в данный момент коммит.
Введите :Gbrowse, чтобы открыть выбранный коммит в веб-интерфейсе GitHub.
Нажмите gq, чтобы вернуться в главный буфер.

Если вам нужна дополнительная справка, введите :help Gblame.

Нахождение pull-запроса, с которого начался коммит

С помощью просмотра истории вы можете получить SHA коммита, но само сообщение, приложенное к коммиту, может и не нести какой-либо полезной информации. Однако если ваша команда использует GitHub Flow, объяснение коммита может быть найдено в обсуждении pull-запроса:

			$ git log --merges --ancestry-path --oneline <SHA>..origin | tail
...
bc4712d Merge pull request #42 from sticky-sidebar
3f883f0 Merge branch 'master' into sticky-sidebar

В этом случае SHA коммита было достаточно, чтобы определить, что он взял начало с pull-запроса #42.

Git-pickaxe

Иногда приходится искать что-то пропавшее — например, обращение к функции, которая больше ниоткуда не вызывается. В таком случае лучше всего использовать команду git log с поиском по ключевому слову:

			$ git log -S<string>

Таким образом вы можете найти коммит, который, к примеру, убрал вызов определенной функции или добавил новый класс.

git churn

Можно взглянуть на историю проекта, не только подробно изучая один коммит, но также и анализируя изменения в целом. Это делается скриптом git-churn, который использует git log, чтобы собрать статистику о файлах, которые редактировали больше всего. Например, чтобы увидеть, на чем фокусировалась разработка приложения за последние 6 месяцев:

			$ git churn --since='6 months ago' app/ | tail

С помощью такого анализа можно выявить потенциальные проблемы в проекте. Если какой-то файл меняется слишком часто, скорее всего, это значит, что в нем слишком много багов, и его стоит переработать, или же на нем лежит слишком много ответственности, и его следует разбить на несколько отдельных.

Таким же образом можно определить, какие люди ответственны за изменение какой-то части приложения. Например, чтобы определить, кто совершил наибольший вклад в API:

			$ git log --format='%an' --since='6 months ago' app/controllers/api/ | \
    sort | uniq -c | sort -rn | head

 109 Edmond Dantès
  13 Jonathan Livingston
   7 Ebanezer Scrooge

Творение истории

Не забывайте, что все ваши изменения войдут в историю проекта и останутся там навсегда. Чтобы облегчить жизнь людям, которые работают с вами, всегда держите в голове следующие правила:

Пишите комментарии к коммиту так, как будто вы объясняете его коллеге, который сидит рядом с вами и не имеет понятия о том, зачем вы это делаете это. Для начала прочитайте эту статью и при каждом коммите отвечайте на следующие вопросы из нее:

Избегайте в одном и том же коммите изменений, не относящихся к главной проблеме. Если вы заметили опечатку или немного переработали код в том же файле, где делали остальные изменения, сопротивляйтесь искушению смешать их в одну кучу с главной проблемой.
Подчищайте историю. Если коммиты еще не были опубликованы, лучше всего убрать из них все лишнее. Все, что изображено на картинке ниже, могло остаться в истории проекта Faraday, но я оставил всего лишь два коммита и исправил сообщения, прикрепленные к ним, чтобы скрыть тот факт, что у меня были проблемы с настройкой скрипта:
Придерживайтесь стиля, который бы позволял вам изменять, удалять или добавлять значения из списков, не трогая соседние строки. Вот несколько примеров: var one = "foo" , two = "bar" , three = "baz" // такой стиль позволяет удалить переменную или добавить новую, // не трогая соседние строки # Ruby: result = make_http_request( :method => 'POST', :url => api_url, :body => '...', // Ruby разрешает оставить в конце запятую, ) // тем самым позволяя добавлять/удалять параметры, не трогая остальные

Небольшой бонус

Раз вы дочитали досюда, я награжу вас небольшим скриптом. Он называется git-overwritten и показывает разработчиков, которые вносили изменения в указанную вами ветку:

			$ git overwritten feature origin/master

  28 2014-02-04 1fb2633  Mislav Marohnić: Add Makefile for building and testing
   1 2014-01-13 b2d896a  Jingwen Owen Ou: Add -t to mktemp in script/make
  17 2014-01-07 385ccee  Jingwen Owen Ou: Add script/make for homebrew build

Это может быть полезно, когда вы делаете pull-запросы с помощью GitHub Flow и хотите обсудить их с коллегами, но не уверены, кого стоит спрашивать. С помощью этого скрипта вы можете получать имена людей, чьи строки вы собираетесь менять, так что вы будете знать, кого @-упоминать при открытии pull-реквеста.

Перевод статьи «Every line of code is always documented»

5788