Not_simple & ByteBoss
Not_simple
Привет, БайтБосс, ты когда-нибудь задумывался, больше похоже на то, как мы комментируем код, на поэзию или на математическое доказательство? Я всё время мучаюсь с тем, нужен ли комментарий, как сноска, или это просто лишний шум.
ByteBoss
Комментарии – это просто дополнительные уравнения, которые ты пишешь рядом с кодом. Если строка кода сама по себе понятна, то подпись не нужна. Относись к комментарию как к шагу доказательства: добавляй его только если он проясняет то, что сам код не показывает. Если он просто повторяет, что делает строка – это шум. Делай их короткими, ясными и только когда нужно объяснить что-то, что не очевидно. Так код остаётся чистым, а комментарии – полезными, а не просто красивой ерундой.
Not_simple
Слушай, ты как бы намекаешь, что комментарии – это как сноски к книге? Но если в коде уже есть строка: "добавляет два", это сноска или просто напоминание? Я постоянно возвращаюсь к мысли, перекомментирую я или недокомментирую, и не могу решить, пишу ли я полезное или просто заполняю поля словами. Стараюсь делать заметки короткими, в одно предложение, но всё равно что-то вроде запятой застряло в голове – сомнения, в общем.
ByteBoss
Если в коде уже указано "добавить два", то комментарий лишний. Относись к комментариям как к шагам доказательства, которые сам код не может продемонстрировать. Оставляй их, если они объясняют компромисс, подводный камень или почему ты выбрал тот или иной алгоритм. Иначе – выкидывай. Одной фразы достаточно – главное, чтобы она была полезной. Если сомневаешься – пропускай; всегда проще добавить потом, если понадобится.
Not_simple
Понятно, но каждый раз, когда я пишу комментарий, кажется, будто я оставляю цепочку подсказок, которая может никуда не привести. Поэтому я постоянно топчусь между двумя вариантами. Постараюсь писать кратко, только чтобы объяснить тот небольшой участок, который мне неясен в коде. Если не получится – пусть будет тихой пометкой на полях, пока не появится необходимость.
ByteBoss
Звучит неплохо. Относись к комментариям как к подстраховке – оставляй их только тогда, когда код сам по себе не объясняет, что происходит. Если по строчке всё понятно без подсказок, забудь про подсказки. Так и будет понятная и полезная картина.
Not_simple
Ну, я буду считать комментарии чем-то вроде вспомогательных конструкций, но оставлять только самое необходимое – как страховку, которая ловит только неожиданные провалы, а не каждый шаг, который уже виден в коде. Если что-то кажется просто заглушкой, я оставлю это в сторону, пока не убежусь, что это действительно важно.