Надлежащие сообщения о фиксации
Для чего сообщения о фиксации? Я всегда писал им как объяснение того, что я сделал, но я недавно вошел в дискуссию об этом с коллегой, который пишет сообщения о фиксации, объясняющие, почему он сделал. Какой является правильным, или является там другим ответом полностью?
Примечание: У меня нет абсолютно никакой идеи, если существует "правильный" ответ для этого. По сути, я маркировал это общественной Wiki и не приму ответ. Upvotes должен решить победителя :)
4 ответа
Я думаю, оба варианта полезны. Быстрое описание того, что изменилось ("Добавление проверки длины для AddUserForm"), проще, чем просмотр diff, особенно если вы просматриваете несколько коммитов. Зачем было сделано изменение, какую ошибку оно исправило и т.д., очевидно, тоже очень полезно иметь.
Я использую сообщение о фиксации как резюме того, что было изменено.
Исполнительное резюме - это [...] короткий документ, который обобщает [...] таким образом, чтобы читатели могли быстро ознакомиться с большим объемом материала без необходимости читать его целиком.
То, почему, документируется в другом месте: система отслеживания проблем, документация по требованиям и т.д. Я также включаю ссылки из сообщения о фиксации на почему, и наоборот.
Как личное предпочтение, я могу сказать, что было сделано, глядя на различия в файлах напрямую. почему - это то, о чем я не могу сделать вывод, просто посмотрев на фактические изменения.
Если изменения значительны или сложны, то я бы включил не только "почему", но и краткий обзор как.
Сообщения фиксации - это то, что вы делаете из них, но когда их сотни для конкретного файла или тысячи для проекта, вы хотите иметь возможность просматривать их в поисках определенных изменений или характера изменений. По сути, они похожи на комментарии к коду, и они должны быть максимально полезными, но при этом краткими и содержательными. Может быть, лучше думать о них как о твитах - передать максимум смысла в коротком промежутке.
Как человек, который работал над большими базами кода на протяжении десятилетий, а также над небольшими проектами, охватывающими год или два, я не нашел ничего более раздражающего при просмотре журналов фиксации, чем сообщения типа «упс» или «исправленная ошибка». Если вы исправили ошибку, сообщите нам, какую (по крайней мере, номер ошибки). Все это важно для неизбежной судебной экспертизы в будущем.