Комментарии к коду - "за" и "против"

Разработка программного обеспечения является сложной задачей со всех точек зрения. Мало того, что задача программирования часто сопряжена с трудностями, когда человек сталкивается с работой над чужим кодом, в котором не используются комментарии, так эта работа еще и усложняется в геометрической прогрессии.

Подумайте об этом так: Представьте, что вам дали все ингредиенты для выпечки хлеба, но не дали рецепта. Вы знаете, что сухие ингредиенты сочетаются друг с другом, но не знаете их количества. То же самое можно сказать и о комментариях к коду, которые могут служить своего рода кратким изложением того, как программист использовал ту или иную функцию или как что-то было изменено для решения определенной задачи.
Комментарии к коду очень важны для эффективного и результативного программирования. Один из основателей ESK Solutions однажды сказал: "Читать код сложнее, чем писать его". Почему это так? Отчасти причина в плохом комментировании. Когда разработчики не комментируют свой код, расшифровать происходящее становится практически невозможно. Но при наличии надежной дорожной карты из комментариев разобраться в этом миазме кода становится гораздо проще.
Итак, для тех, кто хочет помочь своим разработчикам улучшить их работу, какие "за" и "против" комментирования кода? Давайте посмотрим.

Используйте комментарии как способ общения

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

Пишите комментарии, имея в виду другого человека

Аналогичным образом разработчики должны учитывать, что комментарии должны быть написаны с учетом интересов других людей. Этот инструмент нужен не только для того, чтобы оставить себе заметку о своей работе, но и для того, чтобы помочь другим расшифровать то, что они сделали.
Одно из основных назначений комментариев - помочь другим программистам понять, что происходит в коде. Это означает, что ваши разработчики должны писать так, чтобы любой разработчик мог открыть их работу и понять, что происходит.

Работа по устранению путаницы

Комментирование кода должно служить цели устранения путаницы в коде. Речь идет не о демонстрации своей работы, а об упрощении процесса совместной работы и понимания. Сделать свою работу понятной и очевидной должно быть целью номер один при комментировании кода.
Это также означает, что комментарии вашего разработчика должны быть предельно ясными и четкими (и не вносить еще большую путаницу).

Предоставляйте ссылки на оригинальный источник скопированного кода

Если ваши разработчики копируют код из других источников, они всегда должны оставлять ссылки на оригинальные источники. Почему? Потому что тому, кто пойдет по их стопам, может понадобиться понять, почему они использовали этот код, каков был его первоначальный замысел, и даже связаться с разработчиком скопированного кода.

Добавляйте комментарии при исправлении ошибок

Комментарии к коду нужны не только для оригинального (или скопированного) кода, но и для тех случаев, когда ваши разработчики исправляют ошибки. Эти комментарии должны объяснять, что именно они сделали для исправления ошибки и почему это было необходимо. Однако, опять же, разработчики не должны писать в комментариях длинные "как", а должны быть точны и эффективны в своих формулировках.

Используйте аннотации или теги к коду

Для краткости изложения разработчикам следует использовать аннотации и теги кода. Например, @desc - это описание, @param - описание параметров, @returns - описание возвращаемого результата, а @throws - описание возможных типов ошибок. Большинство разработчиков должны хорошо разбираться в таких аннотациях и тегах. Если это не так, обязательно ознакомьтесь с ними.

Пишите комментарии во время написания кода

Вместо того чтобы возвращаться после завершения работы над кодом и вставлять комментарии, разработчики должны писать их по ходу работы. Это позволит избежать многих проблем. Во-первых, разработчик не забудет, почему он сделал то или иное действие. Во-вторых, если с разработчиком что-то случится в середине проекта, комментарии уже будут на месте, и кто-то сможет продолжить работу без особых проблем.

Не комментируйте все подряд

Важно также, чтобы разработчики понимали, что им не следует комментировать все подряд. Разработчики не должны комментировать очевидное. Эта ошибка часто встречается у начинающих программистов, которым кажется, что они должны документировать все, что они создают по ходу работы.
Чтобы помочь в этом вопросе, попросите разработчиков подумать, соответствует ли то, что они пишут, общепринятым соглашениям и синтаксису, а значит, скорее всего, не нуждается в комментариях.

Не используйте комментарии вместо документации

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

Не ссылайтесь на другие комментарии в своих комментариях

Если ваши разработчики ссылаются на другие комментарии (или даже на другие документы), то это означает, что они дают другим разработчикам больше работы, чем нужно. Рассмотрим следующий пример: Разработчик размещает в коде комментарий, который ссылается на другой комментарий. Это означает, что разработчику, который последует за ним, придется искать в коде комментарий, на который он ссылается. Это слишком много работы.
Вместо того чтобы ссылаться на другой комментарий, ваш разработчик должен четко сформулировать то, что ему нужно сказать (и сделать это эффективно). Цель должна заключаться в том, чтобы дать другим меньше работы, а не больше.

Заключение

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