Писать комментарии или не писать комментарии, вот в чем вопрос.

В мире разработки программного обеспечения книги Джона Оустерхаута «Философия дизайна программного обеспечения» и Чистый код Роберта К. Мартина (дяди Боба) предлагают разные точки зрения, через которые можно рассматривать комментирование кода. Оустерхаут подчеркивает необходимость создания изначально понятных программных продуктов, которые сводят к минимуму потребность в комментариях, а дядя Боб в «Чистом коде» предполагает, что лучший комментарий — это тот, который, по вашему мнению, не нужен. Оба подчеркивают, что комментарии не должны компенсировать плохой код. Подготовив все это, давайте углубимся в идеи Оустерхаута об эффективном комментировании.

Характеристики эффективных комментариев Оустерхаута:

  1. Объясните «Что» и «Почему», а не «Как»: хорошие комментарии поясняют, что делает фрагмент кода и почему это необходимо, предлагая контекст и намерение. Рассуждения, будь то выбор конкретного алгоритма или обходной путь, дают неоценимую информацию. Хотя в хорошо написанном коде механика «как» должна быть очевидна, комментарии лучше всего использовать, чтобы пролить свет на неочевидные решения или сложные обоснования.
  2. Предоставьте неочевидную информацию. Хороший комментарий содержит информацию, которую не сразу различить из самого кода. Не следует констатировать очевидное.
  3. Избегайте избыточности. Комментарии не должны повторять то, что код уже ясно дает понять. Избыточные комментарии могут скорее отвлекать, чем помогать.
  4. Комментарии как предупреждение. Комментарии могут выступать в качестве предупреждающего знака, указывая на сложные части кода, которым может потребоваться дополнительное внимание.
  5. Комментарии к задачам. Если для определенного раздела кода запланированы будущие действия или улучшения, в комментариях можно указать это с помощью примечаний «TODO», но их следует использовать разумно.
  6. Обоснование решения. Если существовало несколько способов реализации определенной части функциональности и конкретный подход был выбран по определенной причине, это обоснование можно задокументировать в комментарии.
  7. Общий обзор. В начале модуля или класса комментарии могут дать общий обзор его назначения и поведения, предоставляя контекст для тех, кто погружается в код.
  8. Используйте умеренно. Не следует злоупотреблять комментариями. Если все подробно комментируется, это может затруднить чтение кода. Цель состоит в том, чтобы достичь баланса, при котором код в первую очередь не требует пояснений и при необходимости дополняется комментариями.
  9. Держите их в курсе. Устаревшие комментарии, не соответствующие коду, хуже, чем полное отсутствие комментариев. Они могут ввести в заблуждение и запутать читателей. При обновлении кода крайне важно также обновлять связанные комментарии.

Комментарии высокого и низкого уровня

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

Заключение

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