Правильное оформление комментариев, пояснений и документации в исходном коде

[Igors]

Если каждый день убивается 5-10 функций:

А что здесь удивительного? Если задача, например, перевести UI со старого на тот же Qt - то гораздо больше

* для проекта с количеством участников == 1 - нужно учится проектировать;

Проигнорировано

* для проекта с количеством участников > 1 - нужно увольнять архитектора.

Если он вообще есть. Реальная ситуация (без кавычек): есть 2 программиста а работы/заказов сейчас много. Нужно взять еще одного. Кто будет заниматься архитектурой и .т. п ?

[BRE]

Если каждый день убивается 5-10 функций:

А что здесь удивительного? Если задача, например, перевести UI со старого на тот же Qt - то гораздо больше

Я писал о разработке нового приложения.

* для проекта с количеством участников == 1 - нужно учится проектировать;

Проигнорировано

Я не хотел тебя обидеть. 
Но проектировать нужно учиться постоянно.
Еще Питер Нортон, кажется, писал (не дословно): Когда программа закончена, начинаешь понимать как ее нужно было писать.

* для проекта с количеством участников > 1 - нужно увольнять архитектора.

Если он вообще есть. Реальная ситуация (без кавычек): есть 2 программиста а работы/заказов сейчас много. Нужно взять еще одного. Кто будет заниматься архитектурой и .т. п ?

Для реального проекта, нужно потратить определенное время (не 15 минут), совместно все спроектировать и задокументировать(!). Определить необходимые сущности, сформировать классы, продумать взаимодействия всех участников системы. Если этого не сделать, то в лучшем случае выйдет одна версия программы, которую в дальнейшем невозможно будет расширять и сопровождать. Если продукт с плохой архитектурой начать расширять,  качество продукта, как правило, начнет ухудшаться, что приведет к уменьшению заказов. Такова жизнь.
Кстати, о важности проектирования, написано уйма книг. И даже хорошо спроектированную систему, без нормального документирования, очень сложно сопровождать.
Попробуй вернуться к своему же проекту этак через год и что-нибудь добавить. Сколько времени тебе понадобиться, что бы вспомнить все нюансы? А с документацией это будет на порядок быстрей.

[BRE]

Напишу про себя.
Когда я пишу что-то, то сразу особо документированием не занимаюсь, комментирую в коде тонкие места, фиксы и TODO. В какой то момент, когда какая то подсистема готова (это может быть и 1 класс и 10) и браться за что-то новое нет желания, вот тогда я могу посвятить час-другой нормальному документированию (хотя внутренний голос мне подсказывает, что я все равно очень кратко это делаю). 

[Igors]

Для реального проекта, нужно потратить определенное время (не 15 минут), совместно все спроектировать и задокументировать(!). Определить необходимые сущности, сформировать классы, продумать взаимодействия всех участников системы. Если этого не сделать, то ..

Ой, как оно красиво на словах А на деле "совместно все спроектировать" часто скандал с неприятным осадком. Один упрется рогом что это должно быть только "private" и объявлять friend'ов не моги! Нарушается, дескать, концептуальная чистота. Другой скажет что он в гробу видал все эти классики и виртуальчики и что он на своем С сделает это в 10 раз быстрее. Третий будет совать STL во все возможные и невозможные места. В итоге - лебедь, рак и щука.

Ладно, это уже флуд, умолкаю.

[BRE]

Ой, как оно красиво на словах А на деле "совместно все спроектировать" часто скандал с неприятным осадком.

Можно разделить все на законченные подсистемы, хорошо(!) продумать взаимодействие (интерфейс) этих подсистем, задокументировать это и разойтись. А внутри своей подсистемы каждый будет проектировать сам.

Один упрется рогом что это должно быть только "private" и объявлять friend'ов не моги! Нарушается, дескать, концептуальная чистота.

Вспоминаю как перевернула мое восприятие о ООП книга Гради Буч. Как в голове все стало на свои места и я первый раз постарался отойди от C с использованием классов (а я то думал что уже много лет использую ООП на C++). 

[Igors]

BRE, я бы с большим удовольствием обсудил эти проблемы, но, честно говоря, я не вижу как. Дело в том что эффект начинается примерно с 200-300K строк. Для плагина обычно нет завязок/заморочек, проходит любой подход. Проектировать новую задачу с нуля - это кайф! Чувствуешь себя большим, белым и пушистым   Гораздо хуже с "развитием" большой задачи (часто начатой другими программистами много лет назад). Начиная примерно с 500K lines появляются очень неприятные классы которые должны знать "все о всех" (или почти). Глухой провал в предметную область. Классы/интерфейсы, которые считались удачными, не в состоянии выдержать нагрузки новых features, приходится ставить уродливые заплатки. Всем понятно что очень многое устарело но "оно работает" = очень веский аргумент против которого с голым энтузиазмом не попрешь, а заказчик воспринимает разговоры о "модернизации/архитектуре" с большим подозрением и его можно понять - все хотят платить за конкретный результат. К сожалению, в жизни совсем иначе чем в (действительно хорошей) книге

Kuzulis, примите мои извинения за OT.

[BRE]

Igors, да все это понятно, не бывает идеальной архитектуры не бывает идеальных программ. При проектировании старых приложений, разработчики возможно и представить себе не могли, что потребуются фичи, которые нужно добавить сейчас.
Но, разговор идет о документировании. Зачем же "радовать" людей, которым придется сопровождать вашу систему лет через 5, отсутствием нормальной документации?

[Igors]

Зачем же "радовать" людей, которым придется сопровождать вашу систему лет через 5, отсутствием нормальной документации?

А затем чтобы они знали что такое "держать проект" и глупых иллюзий не имели. И старая дока поможет им "як собацi п'ята нога"

[BRE]

А затем чтобы они знали что такое "держать проект" и глупых иллюзий не имели. И старая дока поможет им "як собацi п'ята нога"

Странный какой то спор у нас получается. 
Почему дока должна быть старая, изменился класс (добавили/изменили что-то) - задокументировали. В чем трудности.
Ладно, спорить не хочу, но думаю со временем ты к этому придешь сам или заказчик/начальник будет это требовать от тебя.

[kuzulis]

Кстати, мне разработчик ответил.. оказывается можно локализвать доку гораздо проще, используя Doxygen... при этом в конфигурационном файле Doxyfile для документации на русском достаточно сделать :

Код:

...
OUTPUT_LANGUAGE        = Russian
...

а в исходниках при комментировании писать так:

Код:

...
/*!
	\class TCore
	\version 0.2
	\author Den
	\brief
	\~english Class is core for application.
	\~russian Класс есть ядро для приложения
*/
...

т.е. в Doxygen есть специальные команды с префиксами "\~"

Для того чтобы доку полностью  на англицком сгененрить нужно просто изменить кв конфиге

Код:

...
OUTPUT_LANGUAGE        = English
...

смотреть подробнее тут: http://www.stack.nl/~dimitri/doxygen/commands.html

ЗЫ: оказалось все еще проще!!!

[UVV]

В принципе коментарии должны быть:
1) На своём родном, если ты уважаешь себя и свой язык.
2) Если тебе за коментарии платят, то на том языке за который платят.
3) Если тебе за коментарии не платят, но ты надешся кому-то угодить, то на том языке, для кого пытаешся угодить.

Комментарии должны быть на том языке, который будет понятен большинству, и мыслить при этом лучше глобальнее, чем в масштабах СНГ. Поэтому тут только один вариант - английский. А дополнительно дублировать то же самое на русском - лишняя работа. Комментарии пишутся не для того, что за них платят и чтобы кому-нибудь угодить, а в первую очередь для себя и для других разработчиков.
Всё вышесказанное - imho

В реальном проекте (без open sources)...

А с чего вдруг "реальный проект" не может быть open source?

[Авварон]

покажите нормальный опенсорс проект:) всякие k3b/амарок/миранда в счет не идут - слишком мелко

[Igors]

покажите нормальный опенсорс проект:) всякие k3b/амарок/миранда в счет не идут - слишком мелко

Навскидку

- PNG Lib
- ImageMagic
- ghostscript
- OpenEXR (этот правда с классами/темплейтами и вытекающими заморочками)
- wxWidgets
- YaffRay
- Pane
- SimCloth

Может в названиях/соглашениях немного попутал но все я реально пользовал в разных целях, доволен и оцениваю очень высоко. Другое дело что мои личные шансы на такой крутой open source ...ну как бы это сказать.. не очень велики Так что я буду писать нормальные рабочие комментарии

[SABROG]

Я тут недавно думал насчет международного языка Эсперанто и пришел к выводу, что для программистов он не пригоден. В нем тупо нет большинства терминов о программировании/компьютерах (оно и понятно, язык не вчера изобрели), а существующие - удручают. Поэтому остается только английский. Вот если бы Чарльз Бэббидж родился в России и фирмы Microsoft, IBM, AMD и т.д. и т.п. были русскими, тогда да, можно было бы сказать, что международный язык программистов - русский, потому, что Post при загрузке компьютера весь на русском, а "Award BIOS" - "Завод Бэббиджа Базовая система ввода/вывода №1253ППЦ". И ключевые слова (keywords) в Си: printf - печатьф, switch - переключатель, while - пока, return - возврат. А internet - ГлобальнаяПаутина, а браузер - Просмотрщик.

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

[UVV]

покажите нормальный опенсорс проект:) всякие k3b/амарок/миранда в счет не идут - слишком мелко

А форум по какой библиотеке вообще? =)
Она, вдруг, стала closed source??