Здравствуйте, меня зовут SiTLar, мне 30 лет и я пишу самодокументирующийся код

в 1:24, , рубрики: идеология, комментарии, Программирование, Совершенный код, метки: ,

Меня давно интересует тема комментирования кода. Этот пост подвиг меня формализовать свою идеологию документирования кода.

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

Слова «описывать все описания » я написал неслучайно, ведь это почти то же что и

std::map<std::string, Person*>mapPPersonsNames //map person pointers by names

Как я дошел до такой еретической жизни?

Когда я был маленьким, я учился программировать на Quick Basic и REXX. Я не брезгал называть переменные a, aa, x1. Потом ко мне пришла ясность, что это определенно плохая идея, потому что на следующий день ничего не понятно. Я стал называть переменные чуть более осмысленно, например money, answer, file_count. В определенный момент я решил напрограммировать punto switcher для OS/2. Естественно, нужно было изучать API и тут я как следует проникся духом самодокументирующегося кода. Названия переменных и имена функций в API OS/2 настолько проработаны, что порой даже не надо было читать описания. Было достаточно увидеть как они обозначены параметры. Мне пришла в голову мысль, почему бы не перенести всю информацию из комментариев прямо в код?

Зачем нужны комментарии в коде?

Это ключевой вопрос в данном посте. Я вижу два достаточно независимых применения. Во-первых нужно как-то понимать, что делают те или иные элементы, чтобы через некоторое время продолжить работу или исправить ошибки. Причем это касается и совместной разработки, когда коллеги должны понимать что и как. Другое применение — сообщить пользователям библиотек, как следует использовать экспортируемые символы, классы, шаблоны.

Я пишу самодокументирующийся код, потому что не хочу тратить время на двойную работу.

Я неспешно двигаю проект в свободное от работы время, под настроение. Перерывы в разработке бывают больше месяца, а объем приличный. У меня не возникает проблем с рефакторингом некоторых частей, потому что в коде достаточно информации. Если называть переменные и функции непонятно, даже с комментариями будет сложно разобраться что происходит.

… здесь надо бы сделать счетчиком цикла i_1, ведь во внешнем цикле i…
Проклятье! i_1 это не по строкам а по столбцам...

Знакома такая ситуация? Надеюсь что нет, потому что совсем нетрудно обходить цикл по uiRowCount и uiColCount. Но в таком случае пропадает смысл в описании этих переменных.

Есть утверждение, что в самодокументирующий код нужно разбивать на большое количество функций. В таком коде сложно разобраться и исполнение замедляется. Лучше развернуть старую добрую портянку, приправить ее комментариями и читать как роман Толстого.

Старая портянка — весьма сомнительное удовольствие. Дело не в читаемости, а в простоте переработки и исправления ошибок. К тому же, факторизованный код как раз лучше в смысле читаемости. Функции — следующий уровень детализации алгоритма. Из названия должно быть ясно, что они делают. Обычно нет необходимости изучать алгоритм во всех подробностях. А если интересует какой-то момент, можно и посмотреть тело функции. Много функций замедляет исполнение? Используйте inline. В то же время, у меня есть функции более чем на сто строк и проблем с читаемостью не возникает.

А как же библиотеки?

Несомненно нужно писать документацию к библиотечным функциям. С точки зрения пользователя лучше, чтобы документация была в отдельном файле. Зачем при этом еще и комментировать весь код? Все нюансы необходимо вынести в описание библиотеки, если конечно нет садистской подоплеки. Я не раз сталкивался с намеком в описании «ну глянь в коде, там все есть.» В действительности это означает, что помимо RPM с библиотекой, нужно скачать исходники. Нужно найти функцию и прочитать комментарии в хедере и в самом коде. Для следующей функции то же самое. grep -R еще ни кто не отменял.

Малоприятная ситуация, не так ли? В то же время, отдельный файл будет распространяться с бинарниками и пользователь только скажет спасибо. Кстати, то же самое касается и описания архитектуры или иерархии классов. Если есть сложные цепочки, почему бы не описать их в отдельном файле?

Автор: SiTLar

Источник


* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js