Комментирование кода средствами VCS 22.11.2017

Снова возвращаюсь к теме комментариев, о которых уже говорил в заметке Комментарии в коде: за и почему напротив. Не так давно в книге «Джез Хамбл, Дейвид Фарли. Непрерывное развертывание ПО» (Jez Humble, David Farley. Continuous Delivery) я наткнулся на ещё один способ размещения комментариев, который в отличие от непосредственного комментирования в листинге кода не создаёт излишнего информационного шума.

Речь идёт о комментариях в теле сообщения к коммиту системы контроля версий, например, Git. Многие привыкли, что сообщенияк коммитам как правило содержат краткие описания внесённых изменений, а иногда даже очень краткие. На самом деле, описание коммита может содержать достаточно большой объём текста. Ярким примером может служить, например, автоматически сформированное сообщение при мердже с конфликтами. Как правило, интегрированные среды разработки при просмотре истории изменений отображают только первые строки описаний коммитов, которые как раз и должны содержать краткое описание и ссылку на задачу в системе управления проектами.

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

У подобного способа комментирования кода есть ещё одно преимущество по сравнению с традиционным. Такой комментарий всегда остаётся актуальным, так как привязан к конкретным правкам. Соответственно, невозможна ситуация при которой код будет удалён или перенесён, а комментарий останется на прежнем месте, или наоборот.

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

В каких случаях не следует пользоваться комментариями в сообщениях к коммиту? Если информация в комментарии очень важна для понимания кода и является частью документации к нему.

Итак, комментированием в теле сообщения к коммиту может пользоваться кто угодно, даже ярые противники традиционного способа комментирования.

by 22.11.2017