Почему стоит писать почему
Раньше в сообщении к коммиту я ограничивался только ответом на вопрос “Что?”.
commit 210a1f2df795bf49bfdd08e50d22ba80bac141f1
Author: Anton Kaliaev ...
Date: Mon Apr 14 13:20:06 2014 +0400
raise NoSlidesError if no slides
Что сделали, то и пишем:
- добавили - added
- удалили - removed
- отрефакторили - refactored
- … ну вы поняли.
Это позволяет быстро понять что было сделано в рамках данного коммита.
Со временем я осознал, что у данного подхода есть один серьезный минус - он не отвечает на вопрос “Почему это было сделано?”. Позже я убедился, что в некоторых ситуациях это способно сильно осложнить жизнь простому разработчику.
Рассмотрим случай выше. Непонятно почему мы бросаем исключение, а не логгируем ошибку. Мы уже не можем быстро поменять данную функциональность. Приходится самому додумывать причину. Словом при отсутствии причины внесения изменений увеличивается стоимость поддержки данного кода.
commit 210a1f2df795bf49bfdd08e50d22ba80bac141f1
Author: Anton Kaliaev ...
Date: Mon Apr 14 13:20:06 2014 +0400
raise NoSlidesError if no slides
This is exceptional situation because if there are no slides, layout
looses it's meaning.
Теперь становится ясно, что в случае отсутствия слайдов лейаут теряет свой смысл. Мы ожидаем, что будет присутствовать хотя бы один слайд.
Прошу вас, не вдавайтесь в терминологию предметной области. Для интересующихся лишь отмечу, что исключение обрабатывается уровнем выше.
Еще пара советов:
-
не используйте
git commit -m "". Она(команда) принуждает вас писать короткие сообщения (например, “fixed nil error”) -
по возможности ссылайтесь на внешние источники информации (номер тикета, ссылка на баг в Airbrake, ссылка на статью в интернете и т.п.)
-
первая строка не должна быть длиннее 72 символов. Следующее после нее расширенное описание может быть любой длинны. В качестве разделителя идет пустая строка.
-
если вы пользуетесь Vim, то можно добавить проверку правописания и ограничение длины текста добавив это в ваш
~/.vimrc:autocmd Filetype gitcommit setlocal spell textwidth=72
Полезные ссылки:
Отдельное спасибо @plugin73 и @SavelyevAndrey за ревью.