Зачем комментируют перед написанием кода?

Question

[VekSide]

Зачем комментируют перед написанием кода?

Answer 1

[mayton2019]

Смыслов много. Во первых исходник не всегда отражает намерения разработчика или есть какая-то информация которая лежит вне этого поля зрения. Например фиксится какое-то сложное поведение кода наподобие undefined behaviour и нужно написать сверху комментарий почему именно сделано так. В противном случае другой разработчик может не понять все эти изменения и откатить их или просто выкинуть кусок кода за непониманием. Такова природа людей. Непонятное - откидываем в сторону. А если будет написано :

// Warning! Do not touch next line of code, because ...

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

Смысл также есть в авто-документировании для авто-документации. По ключевым словам типа Doxygen, JavaDoc можно посмотреть примеры и туториалы по документированию. Это очень хороший навык который сделает в беспорядочной разработке видимость ведения документации. Тут надо конечно идти от scrum-agile и потребностей бизнеса но бывают также проекты (ведомственные, и прочие промышленные) где это важно, и где требуют сопроводительную бумажку. Тулзов для этого много. Я перечислил только 2 но их больше.

Вот что точно не надо комментировать так это : твою подпись, дату-время изменений и заголовок JIRA-ticket на основании которого велась разработка. Вся эта инфа всегда храниться в системах версионного контроля и нет смысла ее дублировать дважды.

Comments

[WbICHA]

Вот что точно не надо комментировать так это : твою подпись, дату-время изменений и заголовок JIRA-ticket на основании которого велась разработка.

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

[mayton2019]

WbICHA, у нас на проектах было такое правило что текст коммита удовлетворяет шаблону. Например если проект имеет код PROJ то комментарий тикета выглядит как
RROJ-001 : Fixed performance bug
Это удобно для среды разработки. Можно в панели git набрать PROJ-001 и сразу увидишь все свои коммиты.

Контролировать такое правило тоже можно там либо хуки были либо какие-то CI/CD скрипты неважно. Главное что если команда договорилась то так и дальше все пойдут строем.

Не совсем понимаю вас почему номер тикета может потеряться. Эта документация живет вечно пока жив проект и я не знаю случаев когда бизнес решал бы удалять сведенья из JIRA/Confluence. Я практически всегда находил самые старые исторические тикеты за 5 и за более число лет.

[WbICHA]

mayton2019, речь не о том. Иметь номер тикета в коммите — это, безусловно, обязательно, но если в самом комментарии в коде не указать номер тикета (в тех случаях, когда его наличие действительно важно), то в истории коммитов он может затеряться. Да, найти его можно, безусловно (хотя если файл переносился/код внутри файла сильно менялся, то просто удачи), но время и силы на поиск нужного коммита, чтобы просто узнать номер тикета.

Answer 2

[mahmudchon]

"Коммента́рии — пояснения к исходному тексту программы, находящиеся непосредственно внутри комментируемого кода. Синтаксис комментариев определяется языком программирования. С точки зрения компилятора или интерпретатора, комментарии — часть текста программы, не влияющая на её семантику."

Answer 3

[Максим Припадчев]

1. Пояснения к коду (когда откроешь спустя время даже свой собственный код он может казаться, как будто чужой).

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

3. Как следствие второго, привычка писать комментарии со временем сделает тебя, как программиста лучше и разовьет важные для успешного программирования качества.