x
 
Александр
13 июля 2017
Советы почтой каждую неделю
Пожалуйста, получите наше письмо, чтобы подтвердить свой адрес:
Вы подписаны на «Советы за неделю»:

Что писать в комментарии к коммиту?


Изме­не­ния в ком­мите (дифф) рас­ска­зы­вают, что изме­ни­лось. Един­ствен­ный спо­соб объ­яс­нить, зачем эти изме­не­ния и какая от них польза — ком­мен­та­рий к ком­миту. Полез­ный ком­мен­та­рий опи­сы­вает не изме­не­ния в коде, а их резуль­тат в мире разработчика:

7279242f add <div> wrap
# Плохо — это мы и в диффе видим. Зачем добав­ляли? Что исправ­ляли?
 
7279242f fix Firefox issue with flexbox padding
# Хорошо — ясно, зачем изме­не­ния, какую про­блему решали
 
 
b1d5272e placeholder
# Плохо — это что? О чём?
 
b1d5272e add missing placeholder to search input in header
# Хорошо — ясно, что попра­вили и зачем
 
 
4f5ed66 bump paperclip
# Плохо — зачем обнов­ляли? На что повли­яло?
 
4f5ed66 update paperclip: adds support for stream downloads for S3 objects
# Хорошо — paperclip обно­вили ради быст­рого ска­чи­ва­ния из S3

Отсюда пра­вило: не что изме­нили, а что и зачем. Помимо этого пра­вила я сове­тую при­дер­жи­ваться ещё одного: писать на англий­ском в пове­ли­тель­ном наклонении.

Ком­мен­та­рии на англий­ском син­хро­ни­зи­ро­ваны с кодом: post в ком­мен­та­рии — post.rb в моде­лях. Если писать ком­мен­та­рии на рус­ском, при­дется дер­жать в голове сло­варь тер­ми­нов: post.rb — это и «пост», и «ста­тья», и «заметка».

Пове­ли­тель­ное накло­не­ние я сове­тую потому, что рас­смат­ри­ваю исто­рию Гита, как после­до­ва­тель­ность команд‑при­ка­зов, пере­во­дя­щих репо­зи­то­рий из одного состо­я­ния в другое:

51537554 mention Ubuntu installation instructions in README

Чтобы при­дер­жи­ваться еди­ного стиля в ком­мен­та­риях к ком­ми­там, шаб­ло­ни­зи­руйте их.

Ещё по теме

P. S. Это был совет о веб‑разработке. Хотите знать всё о коде, тестах, фронтенд‑разработке, цеэсэсе, яваскрипте, рельсах и джейде? Присылайте вопросы.
Вёрстка и прототипирование — дисциплина Школы дизайнеров. Набор закрыт. Оставьте почту, и мы напишем вам, когда откроется следующий набор.
 

Поделиться
Отправить

Цель рубрики — обсуждение вопросов дизайна всех видов, текста в дизайне и взаимоотношений дизайнеров с клиентами.

Мы публикуем комментарии, которые добавляют к уже сказанному новые мысли и хорошие примеры. Мы ожидаем, что такие комментарии составят около 20% от общего числа.

Решение о публикации принимается один раз; мы не имеем возможности комментировать или пересматривать свое решение, хотя оно может быть ошибочно. Уже опубликованные комментарии могут быть удалены через некоторое время, если без них обсуждение не становится менее ценным или интересным.

Вот такой веб 2.0.

Как следить за качеством кода? Часть вторая: метрики Что такое СВГ и как его использовать в ХТМЛ-вёрстке? 1 Джанго или Рельсы? Как следить за качеством кода? Часть первая: зачем




Недавно всплыло

Как найти себе замену 1 Хочу научиться сторителлингу 12 В бюро есть таймтрекинг для сотрудников? 5 2