Несколько советов, как начать правильно комментировать код:

• Быть кратким и лаконичным. 2 Комментарии должны быть короткими: не более 3 предложений для пояснения классов и функций и одного предложения для внутристрочного комментария. 2
• Сохранять единый стиль для каждого уровня. 2 Это поможет любому читающему быстро просмотреть код и понять его структуру. 2
• Объяснять причины, алгоритмы и принятые решения. 1 Комментарии должны отвечать на вопрос «почему», а не просто повторять код. 1
• Обновлять комментарии вместе с кодом. 1 Код часто меняется, и старые комментарии могут привести к недоразумениям. 1
• Включать контекст. 1 Если код связан с какой-либо задачей, багом или требованием, стоит включить ссылку на соответствующий номер или описание. 1
• Практиковать код-ревью. 1 Отзывы и рекомендации от коллег могут помочь выявить недостаточно понятные комментарии или предложить альтернативные способы их написания. 1

Также рекомендуется сначала упростить код до уровня, на котором он станет понятным без дополнительных комментариев. 1