Предварая темку, хочу сказать что фактически я занимаюсь чем-то типа аутсора на дому, т.е. это и не фриланс, где, наверное, для заказчика продукт это действительно черный ящик со входами и выходами – в аутсорсе же твой продукт проверяется работодателем как именно проект (архитектура, алгоритмы, код), но тем не менее это не есть плотное взаимодействие с коллективом… Т.е. «вращайся» бы я в каком-нибудь коллективе очно – может быть таких вопросов и не было :)
Так вот, очень часто, в рекомендациях по оформлению исходного кода, можно встретить мол «в хорошем коде комментарии не нужны. Комментарии заменяет именование».
И вот, сейчас дополняю функционалом некоторый проект. Изначально мои дополнения были в отдельном модуле. И вот я тоже, следуя рекомендации про комментарии, в своём модуле старался давать понятные именования и избегать комментариев.
Это код написанный чисто мной, и я еще не раз буду так или иначе в него возвращаться, и более-менее помнить, что где и для чего… Но вот, настали задачи, где приходится работать уже с чужим кодом. В чужом коде написано с хорошим именованием, возможно даже лучшим чем моим.
Но как я оказался благодарен прошлым разработчика за то, что:
I. Буквально каждый метод любых интерфейсных классов продокументирован (в стиле доксиген).
II. В каких-то алгоритмических штуках (там всякие графы и алгоритмы поиска) важные места кратко описаны в комментариях непосредственно в коде.
III. К проекту есть описательная документация (т.е. такая общая – например, как работают алгоритмы в общем, без привязки к деталям реализации).
Все эти три пункта делают хороший вклад и в ориентировании в коде, и в видении архитектуры продукта и т.п. Без любого из этих пунктов тратилось бы намного больше времени чтобы разобраться. При этом пункты 1, 2 так вообще кажется не потратят много времени на своё сопровождение от разработчика. Да, если в методах много параметров, и много методов с документацией_доксиген этих параметров, и бывает что параметры меняются, и отвлекаться когда «прёт» на отражение изменений в комменты_документации не хочется – ну и пусть. Ведь можно же выделить скажем раз в неделю, в пятницу вечером, время на приведение этих комментов к новым изменениям (исключительно в своей зоне ответственности). А пункт 3 конечно тяжелый, но мне кажется, если это не проект на просто «раз-два и в продакшн» - то для самого себя же возможно пригодится, если случится вернуться к проекту спустя годы…
И вот например в проектах, которые такие доолгие, как колекция компиляторов GCC (по крайней мере STL ++ либа), как ядро Линукса - всё очень хорошо с комментариями.
Там не стесняются писать их в коде, и у каждой ф-ии для каждого параметра в заголовке есть описание. Порой даже (из-за обилия входящих параметров) на имя и параметры ф-ии тратится строчка текста ,а на доксиген_описание параметров – строчек 10. Иногда это может усложнить навигацию по коду, но мне кажется это нормальная плата за ту пользу которую несут столь длинные комменты.
А вот взять не такие дооолгие проекты – Телеграмм, движок Блинк, какие-нить простенькие игры которые по умолчанию в дистрибутивах включаются – в их коде нет комментов. Ладно Xmoto, но над Блинком и Телеграмом, ведь трудятся огромное кол-во людей… Неужели им не мешает отстуствие комментов в коде?
В общем интересно что Вы думаете про комментарии в коде.
1. Ведете ли I,II (а может III) в своих личных проектах?
2. В «корпоративных» проектах – как у вашей компании принято на тему I, II, III – т.е. доксиген_комментариям_к_параметрам_фии_и_её_предназначения(I), комментам_внутри_тела_ф-ии(II), отдельного_описания_логики(III). Может быть у вас даже принято UML схемы составлять и прицеплять их в (III). Расскажите, пожалуйста, очень интересно.
3. Что думаете на тему Блинка, Телеграмма, и прочих больших проектов, код которых открыт – почему там нет комментов? Может быть там все это есть (I,II) но во внутреннем, скрытом репозитории кода, а в открытом – версия без комментов, т.к. возможно именно комменты и описание алгоритмов поверх открытого исходного кода, они воспринимают как интеллектуальную собственность, и поэтому не публикуется?
