1244 подписчика
Сегодня захотелось поговорить о комментировании программ. Надо сказать, дело довольно туманное. Ну если вы сами пишите программы и сами их дорабатываете , то всегда можете сказать, что комментируете так как вам удобно или не комментирую совсем. Но вот как минимум всё же, есть смысл комментировать программный модуль. Для чего предназначен, когда написан, когда дорабатывался. Ну может быть лицензия и автор, если вы распространяете программу. Если это коллективная разработка, то в современных системах программирования такие вещи автоматизированы.
Но этот вариант комментария, даже и комментарием трудно назвать. Просто информация о программе. Она может быть и вообще не в тексте программы. Но о других комментариях. Вот если у вас есть, который вы используете при тестировании и отладке, его естественно следует пометить, чтобы потом удалить. Не дело, когда отладочный код оказывается, что называется, в релизе.
Ещё одну рекомендацию можно встретить в литературе. Это пояснение сложного алгоритма. А вот это как раз вызывает у меня сомнения. Алгоритм авторский, логика автора, язык объяснения авторский. Чаще всего я встречал подобные пояснения, которые не стоило бы даже и читать. Поймите, что есть логика алгоритма, а есть логика автора, который объясняет этот алгоритм. Т.е. такая прокладка. Гораздо проще и полезнее по разбираться в логике алгоритма самому. Разбираться самому всегда лучше, чем разбираться с подсказкой. Если в этом есть необходимость, а иногда и необходимости такой нет. А вот что нужно действительно комментировать, так функцию: 1. Что она делает. 2. Описание параметров. 3. Возвращаемые значения. А вот это внутреннее её содержимое не всегда и нужно знать. А если вы уверены, что она работает некорректно, то просто перепишите её, предварительно ознакомившись в каком контексте она используется в программе.
Есть целый набор того, как не нужно писать комментарии. Например, не нужно пояснять понятный код. Правда выше я уже написал, что и не понятный код также не всегда стоит комментировать. На мой взгляд не стоит комментировать глобальные переменные. Отследить, где она используется и где меняется дело пустяковое. Тем более если используете современную интегрированную среду программирования.
Вообще, когда говорят о читаемости программы, почему-то забывают, что комментарии могут ухудшать и ухудшают читаемость программы. Ведь код программы для меня как бы единый поток. И вдруг на тебе, идут какие-то комментарии, которые мне абсолютно не нужны. Для меня комментарий это всегда разрыв кода и не всегда он оправдан. И вот утверждение давайте запомним: содержимое комментария должно оправдывать его существование, чтобы даже такие как я могли, всплеснув руками, воскликнуть "Смотри как красиво и умно прокомментировал!".
Надо сказать, что у разных авторов вы найдёте самые разные суждения о комментариях. Прочитал как один автор восторженно пишет, что вот каждый шаг алгоритма прокомментирован. Боже ж ты мой, для кого этот комментарий написан? И тут же другой автор пишет нечто противоположное. Ребята, если вы попадёте в среду коллективной разработке, то там есть корпоративные правила, которые вам придётся соблюдать. А всё остальное вы как разработчик должны выработать для себя сами. Если вы разработчик, то у вас достаточно мозгов, чтобы это сделать. Ну а если ... ну вы сами понимаете.
2 минуты
14 октября 2023