German
20 Июня 2021
Прокомментируйте, почему и что
Люди говорят «комментируйте, почему, а не что», идея состоит в том, что код должен быть самодокументированным, а комментарии должны быть только последним средством для объяснения вещей. Комментарии могут рассинхронизироваться, но код всегда остается кодом, поэтому нет необходимости в ненужной избыточности.
Я не согласен: независимо от того, насколько самодокументированный код, комментарии очень помогают в понимании вещей. Каждый раз, когда я возвращаюсь к старому проекту, я нахожу комментарии гораздо более полезными для переориентации, чем мой код или мои тесты.
Общие возражения
Комментарии устаревают
Комментарии могут сбить вас с пути, потому что они устаревают. Код — единственный источник истины.
Хотя лучший процесс программирования исправляет многие из этих проблем, мне не нравятся ответы, которые сводятся к тому, чтобы «стараться больше». Но даже неправильные комментарии могут быть лучше, чем отсутствие комментариев, если их меньшинство! Если у вас нет комментариев, вы должны построить свою мысленную модель кода с нуля, что утомительно и чревато ошибками. С помощью комментариев вы можете проверить, соответствует ли код комментариям, что намного быстрее. Вроде как легче проверить решение NP-полной проблемы, чем решить ее.
Комментарии к раздутым файлам
Ух да я согласен, это реально раздражает. Чем больше у вас комментариев, тем меньше кода вы можете одновременно отображать на экране, а также комментарии визуально отвлекают.
У нас нет хорошо развитой «дисциплины комментариев» в программном обеспечении. Большая часть материала посвящена тому, почему вам не следует писать комментарии или (реже) почему вы должны это делать. Очень мало информации о том, как должны выглядеть комментарии, о методах комментирования или комментировании тематических исследований. Тогда люди не знают, как писать хорошие комментарии, поэтому они говорят, что «комментарии бесполезны», так что никто не развивает дисциплину комментариев.
Комментарии хорошие, пишите больше комментариев.
Что думаете?
Одна вещь, которая, как мне кажется, недостаточно обсуждается, когда люди говорят об этом, — это целевая аудитория. Это своего рода кардинальное правило технического письма (или письма в целом, на самом деле), что вы должны знать, для какой аудитории вы пишете, но часто кажется, что комментарии к коду должны быть нацелены на все возможные аудитории.
Если код обильно усыпан комментариями, объясняющими синтаксис языка программирования, люди, которые раньше не знали язык очень хорошо, сочтут это огромной экономией времени и будут вам благодарны. Но люди, которые уже хорошо владеют языком, будут рассматривать его как раздражающий беспорядок, из-за которого просмотр кода требует больше времени.
Учитывая, что над многими базами кода будут работать люди с различным опытом и уровнями навыков, я не уверен, что возможно даже теоретически придумать политику комментирования, которая документирует код оптимально для всех.
P.S. а тут нет фото при добавления вижу.
Там только текст, и я не вижу тут ссылку на группировку @evg