Комментарии
Комментарии
Код похож на юмор: если его приходится объяснять, значит, он плох. — Кори Хаус, архитектор программного обеспечения и автор
Уместные комментарии повышают читаемость кода, а чрезмерные или ненужные могут дать обратный эффект. Как и во всем, здесь важен баланс. Большая часть кода не потребует комментариев, если следовать принципу KISS и разбивать логику на небольшие, понятные части. Хорошо названные переменные и функции говорят сами за себя.
Полезный комментарий отвечает не столько на вопрос «что?», сколько на вопрос «почему?». Принимали ли вы решения, причины которых неочевидны? Есть ли сложная логика, требующая пояснения? Хороший комментарий сообщает то, чего нельзя понять из самого кода. Ниже приведены основные рекомендации по работе с комментариями: — Не заменяйте плохой код комментариями. Если для объяснения запутанной логики нужен комментарий, переработайте код так, чтобы он стал понятнее. Тогда комментарий не понадобится.
— Правильно названный класс, переменная или метод заменяет комментарий. Если код понятен сам по себе, не создавайте лишний шум и обойдитесь без комментария.
// ИЗБЕГАЙТЕ: лишних комментариев, повторяющих очевидное // цель, по которой нужно выстрелить Transform targetToShoot; — По возможности размещайте комментарий на отдельной строке, а не в конце строки кода. Обычно отдельная строка делает его понятнее. — В большинстве случаев используйте однострочные комментарии с двойной косой чертой (//). Размещайте комментарий рядом с кодом, который он поясняет, вместо большого многострочного блока в начале. Так читателю проще связать пояснение с логикой. — Для сериализуемых полей используйте всплывающую подсказку вместо комментария. Если поле в Inspector требует пояснения, добавьте атрибут Tooltip и не создавайте отдельный комментарий: подсказка выполнит обе задачи.
// ПРИМЕР: Tooltip заменяет комментарий
[Tooltip("Величина бокового трения.")] public float Grip;Всплывающая подсказка в окне Inspector
— Перед открытыми методами и функциями также можно использовать XML-тег <summary>. Visual Studio отображает многие стандартные XML-комментарии через IntelliSense.
// ПРИМЕРЫ: // Обычный комментарий. // Используйте комментарии, чтобы показать намерение, ход логики и подход.// Также можно использовать XML-тег <summary>. // /// <summary> /// Управляет системой оружия: стрельбой, перезарядкой и нанесением урона.
// </summary>
public void Fire() { ... }— Между маркером комментария (//) и его текстом ставьте один пробел.
— Добавляйте юридические уведомления. Комментарий подходит для сведений о лицензии или авторских правах, но не вставляйте в код полный юридический документ. Вместо этого дайте ссылку на страницу с полной информацией. — Соблюдайте единый стиль комментариев. Например, начинайте каждый комментарий с прописной буквы и завершайте точкой. Какой бы формат ни выбрала команда, закрепите его в руководстве по стилю и придерживайтесь его. — Не окружайте комментарии декоративными блоками из звездочек или специальных символов. Это ухудшает читаемость и дополнительно загромождает код.
— Удаляйте закомментированный код. Временно отключать строки во время разработки и тестирования нормально, но не оставляйте такой код надолго. Предыдущие версии хранит система контроля версий — смело удаляйте ненужные строки.
— Поддерживайте комментарии TODO в актуальном состоянии. Завершив задачу, удалите оставленный для нее TODO: устаревшие напоминания только отвлекают. Для контекста и персональной ответственности в TODO можно указать имя и дату. Будьте реалистичны. До TODO, оставленного пять лет назад, вы, скорее всего, уже не доберетесь. Следуйте YAGNI: удалите этот комментарий и вернитесь к задаче лишь тогда, когда она действительно понадобится.
— Не превращайте комментарии в журнал разработки. Приступая к новому классу, не нужно записывать в комментариях каждое действие. При правильном использовании системы контроля версий это избыточно. — Не указывайте авторство правок. Подписи вроде // добавлено devA или devB не нужны — эту информацию хранит система контроля версий.
