История изменений
Исправление praseodim, (текущая версия) :
Так вот, очень часто, в рекомендациях по оформлению исходного кода, можно встретить мол «в хорошем коде комментарии не нужны. Комментарии заменяет именование».
Всегда считал это дурацкой рекомендацией. Во всяком случае, неприменимой за пределами каких-то более-менее простых по назначению программ.
Это не значит, что хорошее наименование не важно, но на практике оно помогает максимум в использовании функций и их параметров без подглядывания в справочник.
Этого абсолютно недостаточно. Нужно еще указывать какой алгоритм (если не тривиальное что-то) и почему использован, хорошим тоном будет даже ссылка на книгу и номер страницы и/или сайт в интернете с описанием. Если алгоритм самим разработан, то на базе каких и краткое описание как он работает.
Нужно описывать какие-то сложные случаи, особенно если делается компенсация чужих ошибок.
В общем, все что помогает хотя бы самому спустя годы восстановить ход мыслей, который привел к данному коду.
Документировать же все в наименованиях и невозможно в принципе и слишком длинные наименования могут даже затруднить понимание. Если реализованы какие-то математчиеские формулы чаще проще видеть одно-двух-буквенные имена переменных + ссылка на алгоритм или его описание прямо тут же, чем трудолюбиво выписанные многословные названия.
Ну и собственно сам же и ответил на вопрос
И вот например в проектах, которые такие доолгие, как колекция компиляторов GCC (по крайней мере STL ++ либа), как ядро Линукса - всё очень хорошо с комментариями.
Иначе и быть не могло. А то, что в некоторых проектах комментариев нет еще вопрос почему: не было изначально (и тогда это очень плохо для проекта) или нарочно удалены перед выкладыванием.
Вообще я даже скажу, что для свободы программирования, хорошая документация может быть даже важнее, чем открытый код, но плохо или не документированный.
Исходная версия praseodim, :
Так вот, очень часто, в рекомендациях по оформлению исходного кода, можно встретить мол «в хорошем коде комментарии не нужны. Комментарии заменяет именование».
Всегда считал это дурацкой рекомендацией. Во всяком случае, неприменимой за пределами каких-то более-менее простых по назначению программ.
Это не значит, что хорошее наименование не важно, но на практике оно помогает максимум в использовании функций и их параметров без подглядывания в справочник.
Этого абсолютно недостаточно. Нужно еще указывать какой алгоритм (если не тривиальное что-то) и почему использован, хорошим тоном будет даже ссылка на книгу и номер страницы и/или сайт в интернете с описанием. Если алгоритм самим разработан, то на базе каких и краткое описание как он работает.
Нужно описывать какие-то сложные случаи, особенно если делается компенсация чужих ошибок.
В общем, все что помогает хотя бы самому спустя годы восстановить ход мыслей, который привел к данному коду.
Документировать же все в наименованиях и невозможно в принципе и слишком длинные наименования могут даже затруднить понимание. Если реализованы какие-то математчиеские формулы чаще проще видеть одно-двух-буквенные имена переменных + ссылка на алгоритм или его описание прямо тут же, чем трудолюбиво выписанные многословные названия.