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