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

Стоит ли полагаться на комментарии?

Мысль, которую я считаю очень верной, заключается в том, что при написании кода с самого начала вы должны сделать его как можно более простым, и только в тот момент, когда это уже невозможно, вы должны добавлять комментарии. Для меня лучший код - это исключительно выразительный код, тот, который говорит сам за себя. И лучше написать фрагмент кода иначе, чтобы он был более выразительным, чем оставлять много дополнительных комментариев. Но из любого правила есть исключения. Я также верю в то, что ни один код, простой или нет, не может быть полностью самодокументирован. Бывают случаи, когда добавление комментариев - важная вещь.

Что я имею в виду? Иногда вещи, которые абсолютно ясны и очевидны для одного разработчика, могут быть совершенно непонятными для другого, у которого нет контекста. Конечно, код следует писать с расчетом на читателей, но бывают случаи, когда это невозможно. Даже если мы не должны полностью полагаться на дополнительные объяснения, мы должны знать, какие типы комментариев уместны и имеют право быть на них.

Код - как, комментарии - почему

Если для архивирования какой-либо цели, будь то повышение производительности или что-то еще, вам нужно было написать умный, не слишком прозрачный код, то комментировать ее, вероятно, будет хорошей идеей. То же самое касается случаев, когда вы исправляете ошибку в чужом коде, особенно если этот код непонятен. И после того, как вы, наконец, поняли это, борясь в течение определенного периода времени, переписывание всего может оказаться адской работой и отнимать очень много времени. Не говоря уже о том, чтобы делать это постоянно для каждого неясного кода, в котором вы что-то исправляете. Это безумие! Но оставление комментария занимает всего несколько минут и может сэкономить много времени и проблем следующему разработчику, работающему с ним.

Итак, комментирование кода имеет смысл, но вы должны подумать о том, что вы добавляете в свои комментарии. Им не нужно повторять то, что уже очевидно. Сам код сообщает, как он работает, но почему код находится там, где он находится, и что он там делает - это то, что может потребовать объяснения. Как я уже говорил ранее, комментарии могут сбить с толку и отвлечь внимание. Добавление комментариев, которые просто повторяют то, что написано в коде, только отвлекает внимание человека, который их читает, и может быть действительно раздражающим. Но предоставление в комментариях информации, которую трудно получить из кода, - это ценно. Например, сообщая, с какими аспектами программы имеет дело большой исходный файл, вы обеспечиваете получение ценной информации, что могло бы занять гораздо больше времени для другого программиста.

Ложные комментарии

Специалисты по сопровождению кода не часто приводят комментарии в соответствие с кодом, что может привести к рассинхронизации последнего с кодом и дезинформации. И какая информация может быть хуже неверной.

Может быть трудно сделать, чтобы полностью избежать этого, но уменьшить вероятность вполне управляемо. С этой целью старайтесь, чтобы комментарии были близки к совместимому коду. Обычно комментарии пропускаются и не обновляются, потому что мы не обращаем на них внимания. Также добавляйте комментарии в начало файла, его тему, место, которое не часто меняется, в отличие от реализации файла.

Хорошая идея - комментировать на уровне намерений. Хотя реализация намерения может меняться очень часто, само намерение может оставаться в течение длительного периода времени. Для этого можно использовать комментарии в форме псевдокода, чтобы обозначить намерение. Таким образом, вы объясняете логику кода, то, что он намеревается делать, а не то, как он это реализует.

Другой уровень намерений, который сам код на самом деле плохо выражает, - это то, почему он реализует именно так, а не другой. Так что это может быть ценная информация для разработчиков кода. Если вы пробовали другой дизайн или другой способ реализации этого кода, и это не сработало, включите его в свои комментарии (что вы сделали и каков был результат, почему это не сработало) может помочь по рукам.

Комментировать или не комментировать, каков вывод?

Вы видите, что, глядя с одной стороны, комментарии могут быть отличным инструментом для улучшения вашего кода, а судя по другой - ими можно злоупотреблять, и они только причинят больше вреда. Так что все сводится к вашим личным предпочтениям и суждениям. На мой взгляд, если есть способ сделать код более понятным и выразительным, то сделайте это, если по каким-то причинам это невозможно или даже не ваше дело, то прокомментируйте его. И сделайте это так, чтобы было легче понять, что делает код и почему он делает это именно так. Представьте, что вы говорите то, чего не может код, мужчине рядом с вами. В любом случае лучше оставить полезный комментарий к непонятному коду, чем позволить другому человеку, читающему этот код, сказать: «Что за херня…?».

P.S. Итак, мы рассмотрели две стороны комментариев: хорошие или плохие для кода и тех, кто его читает. В CheckiO мы, безусловно, верим, что пояснительные комментарии могут быть очень полезны в образовательных целях и действительно могут помочь другим людям научиться программировать. Многие из наших пользователей оставляют свои решения различных интересных задач с явными комментариями, иллюстрирующими их логику и подход. Этот обмен знаниями и практикой оказался очень эффективным и плодотворным. Так что присоединяйтесь и покажите нам, как вы делаете свой код, поделитесь своими идеями и не забудьте комментировать, здесь мы ценим ваш вклад.