Russian Qt Forum

Qt => Общие вопросы => Тема начата: kuzulis от Сентябрь 04, 2009, 12:10

Название: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: kuzulis от Сентябрь 04, 2009, 12:10

Доброго дня!

1. Как правильно в исходном коде оформлять комментарии, описания методов и т.п.?
например я делаю так в файлах реализации (*.срр):

Код:

/*! \fn int MyClass::method1(int param1) const
	\private - тут указываю из какой секции метод (public, private, protected ...)
	\brief - это краткое описание назначения метода
\en		- тут на английском назначение
\ru		- тут на русском назначение
	\param param1 - тут входные параметры
\en - на англ
\ru - на русском
        \return int - тут возвращаемое значение
\en - описание возвр знач на англ
\ru - описание возвр знач на русск
*/
int MyClass::method1(int param1) const
{
тут реализация метода
}

2. Где почитать про принятые стандарты ТЭГОВ в таких случаях
3. Для чего используются тэги?

ЗЫ: поделитесь, народ, кто как оформляет исходники: чтобы было красиво, удобно, понятно, и на нескольких языках :)

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: UVV от Сентябрь 04, 2009, 12:26

imho, посмотреть в сторону doxygen. И ещё imho, комментарии должны быть только на английском.

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: navrocky от Сентябрь 04, 2009, 12:35

А это чей язык разметки комментариев был использован? Местами очень напоминает doxygen.

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: UVV от Сентябрь 04, 2009, 12:38

Цитата: navrocky от Сентябрь 04, 2009, 12:35

А это чей язык разметки комментариев был использован? Местами очень напоминает doxygen.

Да, кстати :)

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: kuzulis от Сентябрь 04, 2009, 13:12

Цитировать

А это чей язык разметки комментариев был использован? Местами очень напоминает doxygen.
Да, кстати

Мой + чей-то еще + QTшный :)

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: navrocky от Сентябрь 04, 2009, 13:34

Вопрос не в тему, никто не знает чем qtшники генерят свою красивую документацию?

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: BRE от Сентябрь 04, 2009, 14:11

Цитата: navrocky от Сентябрь 04, 2009, 13:34

Вопрос не в тему, никто не знает чем qtшники генерят свою красивую документацию?

http://www.prog.org.ru/topic_7944_0.html

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: kuzulis от Сентябрь 04, 2009, 15:04

Цитировать

imho, посмотреть в сторону doxygen. И ещё imho, комментарии должны быть только на английском.

хм, но в настройках Doxyfile можно выставить параметр:

Код:

OUTPUT_LANGUAGE        = Russian

и тогда дока сгенерится на русском языке, НО!!! Какие нужно использовать тэги для разделения описания функций, классов, методов и т.п. на поддерживаемые Doxygen языки?

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: UVV от Сентябрь 04, 2009, 16:07

Я имел ввиду в принципе.

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: lit-uriy от Сентябрь 04, 2009, 17:10

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

Название: Re: Правильное оформление комментариев, поя&#
Отправлено: Rcus от Сентябрь 04, 2009, 17:38

Мне кажется что документацию и на одном языке то сложно держать актуальной, а на двух и подавно (и более полезными все равно оказываются более общие описания работы системы, форматов данных и подобное в отдельном документе)
Первый способ который можно попробовать это параметризованные альясы file://///usr/share/doc/doxygen/html/custcmd.html (apt-get install doxygen-doc :D)
Второй способ - держать полные копии, управлять генерацией через препроцессор.
Кстати OUTPUT_LANGUAGE влияет только на язык констант в доках.

UPD: Не дописал первый способ. В общем идея в том что имеется два конфигурационных файла, альясы на ненужные языки раскрываются в пустые выражения, на нужные - в абзацы

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: kuzulis от Сентябрь 05, 2009, 13:06

Цитировать

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

+500 :)

но конечно хотелось бы держать в исходниках например два языка на которых описаны пояснения.

Цитировать

Первый способ который можно попробовать это параметризованные альясы file://///usr/share/doc/doxygen/html/custcmd.html (apt-get install doxygen-doc )

мда, в арче такого нету.. хотя посмотрю ща...

например имею это:

Код:

/*! 
\fn int fun(int param1) const
\brief
\lang <тут например тэг RU (или Russian)>
 тут описание функции на русском
 бла бла бла
\endlang
\lang <тут например тэг EN>
 тут описание функции на английском
 бла бла бла
\endlang
...
...
*/

Как бы так настроить Doxygen, чтобы например при установке OUTPUT_LANGUAGE = Russian - он выдирал только то, что заключено в тэги

Код:

\lang RU
....
\endlang

к примеру...
т.е. неужели разработчику было трудно придумать нечто похожее? и тогда бы сразу отпадали все вопросы...

ЗЫ: неудобно как-то Doxygen сделан... не для всех! :(
ЗЫЗЫ: шоли патч написать? :) Или разрабу письмо паслать?

----

ЗЫЗЫЗЫ: послал письмо разработчику dimitri@stack.nl ждем чо ответят :)

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: kuzulis от Сентябрь 05, 2009, 15:43

Заработало!!!

Пример:

файл *.cpp

Код:

...
/*! \fn TPerunCore::TPerunCore()
	\brief
	\lang_Russian
	Конструктор по умолчанию
	\endlang
	\lang_English
	Default constructor
	\endlang
*/
TPerunCore::TPerunCore()
{
}
...

теперь в конфиге Doxyfile пишем:

Код:

...
OUTPUT_LANGUAGE        = Russian
...
ALIASES                = "lang_English=\if english" \
                         "lang_Russian=\if russian" \
                         "endlang=\endif"
...
ENABLED_SECTIONS       = russian
...

и документация + комменты будут собираться на русском !!!

- если нужно доку на англицком а комменты на русском - то делаем только: OUTPUT_LANGUAGE = English
- если нужно доку на русском а комменты на англицком то делаем только: ENABLED_SECTIONS = english

Оказывается все просто! :)

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: Igors от Сентябрь 05, 2009, 16:00

Цитата: lit-uriy от Сентябрь 04, 2009, 17:10

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

Видимо так же думал один испанский программист чью программу мне пришлось однажды переделывать. Он много писал о какой-то "perdida" а я никак не мог понять что это :) С кириллицей хуже, ее у заказчика может просто не быть. Так что при всем уважении к нашему языку, plain English - оптимальный вариант.

В реальном проекте (без open sources) каждый день 5-10 новых функций появляется и столько же убивается. Охота возиться с примечаниями для каждой пропадает очень быстро. Имеет смысл комментировать:

- члены класса (данные)
- немногие специфические или сложные функции (обычно in/out)
- поддерживаемые форматы

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: BRE от Сентябрь 05, 2009, 16:14

Цитата: Igors от Сентябрь 05, 2009, 16:00

В реальном проекте (без open sources) каждый день 5-10 новых функций появляется и столько же убивается. Охота возиться с примечаниями для каждой пропадает очень быстро.

IMHO!
Это для "реального" проекта с количеством участников == 1 (и то позднее вернуться к проекту без документации значительно сложнее чем с документацией).
Если участников > 1, то без нормальной документации развивать и сопровождать проект становиться невозможно.

Если каждый день убивается 5-10 функций:
* для проекта с количеством участников == 1 - нужно учится проектировать;
* для проекта с количеством участников > 1 - нужно увольнять архитектора.

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: Igors от Сентябрь 05, 2009, 16:37

Цитата: BRE от Сентябрь 05, 2009, 16:14

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

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

Цитата: BRE от Сентябрь 05, 2009, 16:14

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

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

Цитата: BRE от Сентябрь 05, 2009, 16:14

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

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: BRE от Сентябрь 05, 2009, 16:53

Цитата: Igors от Сентябрь 05, 2009, 16:37

Цитата: BRE от Сентябрь 05, 2009, 16:14

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

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

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

Цитата: Igors от Сентябрь 05, 2009, 16:37

Цитата: BRE от Сентябрь 05, 2009, 16:14

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

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

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

Цитата: Igors от Сентябрь 05, 2009, 16:37

Цитата: BRE от Сентябрь 05, 2009, 16:14

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

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: BRE от Сентябрь 05, 2009, 17:02

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: Igors от Сентябрь 05, 2009, 17:34

Цитата: BRE от Сентябрь 05, 2009, 16:53

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

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: BRE от Сентябрь 05, 2009, 17:50

Цитата: Igors от Сентябрь 05, 2009, 17:34

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

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

Цитата: Igors от Сентябрь 05, 2009, 17:34

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

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: Igors от Сентябрь 05, 2009, 20:40

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

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: BRE от Сентябрь 05, 2009, 21:04

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: Igors от Сентябрь 05, 2009, 21:35

Цитата: BRE от Сентябрь 05, 2009, 21:04

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

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: BRE от Сентябрь 05, 2009, 22:52

Цитата: Igors от Сентябрь 05, 2009, 21:35

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: kuzulis от Сентябрь 07, 2009, 09:56

Кстати, мне разработчик ответил.. оказывается можно локализвать доку гораздо проще, используя 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

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: UVV от Сентябрь 10, 2009, 06:12

Цитата: lit-uriy от Сентябрь 04, 2009, 17:10

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

Цитата: Igors от Сентябрь 05, 2009, 16:00

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

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: Авварон от Сентябрь 10, 2009, 21:26

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: Igors от Сентябрь 10, 2009, 21:52

Цитата: Авварон от Сентябрь 10, 2009, 21:26

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

Навскидку

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

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: SABROG от Сентябрь 10, 2009, 21:56

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

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: UVV от Сентябрь 11, 2009, 04:21

Цитата: Авварон от Сентябрь 10, 2009, 21:26

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

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

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: Авварон от Сентябрь 11, 2009, 09:55

а кто сказал что она нормальная?))) да, ей нет аналогов в области, да она удобная, но ее еще улучшать и улучшать и конца этому не видно:)

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: BRE от Сентябрь 11, 2009, 10:03

Цитата: Авварон от Сентябрь 11, 2009, 09:55

Ты бы сразу привел список нормальных, на твой взгляд, закрытых проектов. ;)

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: Авварон от Сентябрь 11, 2009, 10:13

windows))) шучу)
офис мелкомягких
фотожаба (вот тут можно много холиварить:))
прочее графическое по
.net тот же, он только под винду, но зато умеет гораздо больше (но вместе с тем глючный, вернее "фичный")

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: BRE от Сентябрь 11, 2009, 10:18

Цитата: Авварон от Сентябрь 11, 2009, 10:13

windows))) шучу)

Действительно смешно. ;D
kernel.org

Цитата: Авварон от Сентябрь 11, 2009, 10:13

офис мелкомягких

openoffice.org

Цитата: Авварон от Сентябрь 11, 2009, 10:13

фотожаба (вот тут можно много холиварить:))

gimp

Цитата: Авварон от Сентябрь 11, 2009, 10:13

прочее графическое по

blender и другое открытое графическое по

Цитата: Авварон от Сентябрь 11, 2009, 10:13

.net тот же, он только под винду, но зато умеет гораздо больше (но вместе с тем глючный, вернее "фичный")

Это не знаю что такое.

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: UVV от Сентябрь 11, 2009, 10:35

> blender и другое открытое графическое по
Для тех, кто не в курсе, большинство современных мультфильмов делают именно в нём. Например, "В поисках Немо".

Название: Re: Правильное оформление комментариев, пояснений и документации в исходном коде
Отправлено: lit-uriy от Сентябрь 11, 2009, 16:47

>>покажите нормальный опенсорс проект
Firebird, MySQL неа?
(Хочу больше (http://ru.wikipedia.org/wiki/Категория:Свободное_ПО_по_назначению))