Как правильно комментировать код
Чем комментарии могут помочь программисту
Комментарии — поясняющие строки в программном коде, которые позволяют понять смысл написанного. Они пишутся для людей, но игнорируются компиляторами и интерпретаторами.
Комментарии, в зависимости от ситуации, делают сразу несколько полезных вещей:
1. Помогают быстрее разобраться в коде — если появилась ошибка или нужно что-то изменить d программе.
Это важно и разработчику, и тем, кто будет заниматься кодом после него.
2. Не дают запутаться в логике — при создании новых библиотек, процедур,
функций и системных переменных.
3. Объясняют результаты работы — при отладке или проверке программы.
Это понимание необходимо тестировщикам из отдела QA.
4. Описывают сложные алгоритмы и формулы — в математических,
физических или экономических расчётах и других сложных вычислениях.
Это позволяет разобраться
в готовом коде тем, у кого нет глубоких знаний в какой-то
предметной области.
Комментарии нужны даже в языках с русскоязычным синтаксисом, вроде 1C или ДРАКОН. Может показаться, что там все и без комментариев понятно, но это опасное заблуждение: русскоязычный код забывается так же легко, как и англоязычный.
Документирующие и поясняющие комментарии
В зависимости от того, для чего нужны комментарии,
их условно делят на два вида:
Поясняющие логику кода, использование алгоритмов.
Разработчики применяют их на своё усмотрение.
Документирующие — обязательные комментарии, содержащие информацию о назначении
объектов, входных и выходных параметрах (если они есть), данные о
разработчике и других важных вещах, относящихся к фрагменту кода.
Они располагаются в заголовках модулей, библиотек, процедур и функций.
Из такого комментария сразу ясно, что делает программа. Не нужно вникать в исходный текст и изучать техническую документацию. Это особенно важно, если вы работаете в команде и хотите сэкономить время коллег.
Как комментируют функции и библиотеки
В комментариях к файлам и библиотекам указывают
информацию о проекте, назначении модуля,
заносят в них имя разработчика, номер версии продукта и
лицензию на программное обеспечение.
Например, документирующий комментарий из заголовка
библиотеки Lodash для JavaScript выглядит так:
Кроме этого, в заголовочных комментариях
к функциям указывают стандартный набор сведений:
описание того, что и как делает функция/процедура;
условия, при которых она работает или не работает;
описание входные параметров, если есть;
описание возвращаемого значения.
