Чаще требуется технологическое описание алгоритма, а не комментарии по его реализации, а вот этого никто не желает делать, кроме как в курсовых студенческих работах или диссертациях.
В "Верёвке достаточной длины..." (откуда цитата, в ответ на "программирование - мышление категориями, а не литературное понимание") комментариям повещена отдельная глава, и как раз к такому выводу и приводит читателя автор. Реализация обычно понятна из кода, а вот картина в целом - нередко напоминает детектив, особенно для непривыкших реверсить машкод.
А что, комментарии обязательно должны быть именно в коде? Вы проект делали хоть раз? Обычно пишешь софт, а к нему идёт документация - там всё - обучение, описание всех файлов, алгоритмы с расшифровкой всех используемых параметров, и т. п.
Проект - это не просто сделать (обратите внимание на совершенное время глагола), а что бы он прожил хотя бы лет 10. И что бы не возникала ситуация, когда в документации одно, а код 5 лет как убежал вперёд. Потому придумали doxygen, QDoc, Javadoc и подобные инструменты - они автоматически генерируют документацию из специальным образом оформленных комментариев.
И будьте любезны, не поленитесь показать для примера парочку таких "обычных" проектов (знаю-знаю, свои под NDA, потому сгодятся чужие). MSDN я и сам видел, но писали его не люди с форума, и даже там не все параметры расшифрованы.
А то обычно почему-то вот так:
The window hierarchy
TODO
Last edited Sat 29 Mar 2014 03:59:04 PM UTC
Это - один из ключевых для Linux проектов,
XCB. Любой эксперт объяснит, что X11 рулит, а модно-молодёжный Wayland должен умереть. Вот только факты вещь упрямая...
