Писать комментарии или не писать комментарии, вот в чем вопрос.
В мире разработки программного обеспечения книги Джона Оустерхаута «Философия дизайна программного обеспечения» и Чистый код Роберта К. Мартина (дяди Боба) предлагают разные точки зрения, через которые можно рассматривать комментирование кода. Оустерхаут подчеркивает необходимость создания изначально понятных программных продуктов, которые сводят к минимуму потребность в комментариях, а дядя Боб в «Чистом коде» предполагает, что лучший комментарий — это тот, который, по вашему мнению, не нужен. Оба подчеркивают, что комментарии не должны компенсировать плохой код. Подготовив все это, давайте углубимся в идеи Оустерхаута об эффективном комментировании.
Характеристики эффективных комментариев Оустерхаута:
- Объясните «Что» и «Почему», а не «Как»: хорошие комментарии поясняют, что делает фрагмент кода и почему это необходимо, предлагая контекст и намерение. Рассуждения, будь то выбор конкретного алгоритма или обходной путь, дают неоценимую информацию. Хотя в хорошо написанном коде механика «как» должна быть очевидна, комментарии лучше всего использовать, чтобы пролить свет на неочевидные решения или сложные обоснования.
- Предоставьте неочевидную информацию. Хороший комментарий содержит информацию, которую не сразу различить из самого кода. Не следует констатировать очевидное.
- Избегайте избыточности. Комментарии не должны повторять то, что код уже ясно дает понять. Избыточные комментарии могут скорее отвлекать, чем помогать.
- Комментарии как предупреждение. Комментарии могут выступать в качестве предупреждающего знака, указывая на сложные части кода, которым может потребоваться дополнительное внимание.
- Комментарии к задачам. Если для определенного раздела кода запланированы будущие действия или улучшения, в комментариях можно указать это с помощью примечаний «TODO», но их следует использовать разумно.
- Обоснование решения. Если существовало несколько способов реализации определенной части функциональности и конкретный подход был выбран по определенной причине, это обоснование можно задокументировать в комментарии.
- Общий обзор. В начале модуля или класса комментарии могут дать общий обзор его назначения и поведения, предоставляя контекст для тех, кто погружается в код.
- Используйте умеренно. Не следует злоупотреблять комментариями. Если все подробно комментируется, это может затруднить чтение кода. Цель состоит в том, чтобы достичь баланса, при котором код в первую очередь не требует пояснений и при необходимости дополняется комментариями.
- Держите их в курсе. Устаревшие комментарии, не соответствующие коду, хуже, чем полное отсутствие комментариев. Они могут ввести в заблуждение и запутать читателей. При обновлении кода крайне важно также обновлять связанные комментарии.
Комментарии высокого и низкого уровня
При обсуждении комментариев важно различать комментарии высокого и низкого уровня. Комментарии высокого уровня предоставляют обзор, предлагая макро-перспективу. Обычно они находятся в начале модулей или функций и описывают назначение, взаимодействие и общее поведение. С другой стороны, комментарии низкого уровня фокусируются на определенных строках или блоках кода, подробно описывая сложную логику или подчеркивая потенциальные ошибки.
Заключение
Комментарии — это больше, чем просто аннотации в вашей кодовой базе. Это форма искусства, которая, если ее тщательно создать, может направлять, просвещать и экономить время любого разработчика, изучающего код. Однако они никогда не должны становиться опорой для неясного кода. Золотое правило остается неизменным: создавайте программное обеспечение, которое легко понять, а затем используйте комментарии для повышения, а не замены ясности. Как утверждают и Оустерхаут, и дядя Боб, нашей главной целью должен быть чистый, понятный код с комментариями, играющими вспомогательную роль.