Russian Qt Forum
Ноябрь 26, 2024, 08:29 *
Добро пожаловать, Гость. Пожалуйста, войдите или зарегистрируйтесь.
Вам не пришло письмо с кодом активации?

Войти
 
  Начало   Форум  WIKI (Вики)FAQ Помощь Поиск Войти Регистрация  

Russian Qt Forum > Forum > Qt > Общие вопросы > Правильное оформление комментариев, пояснений и документации в исходном коде
Страниц: [1] 2 3   Вниз
« предыдущая тема следующая тема »
  Печать  
Автор Тема: Правильное оформление комментариев, пояснений и документации в исходном коде  (Прочитано 25312 раз)
kuzulis
Джедай : наставник для всех
*******
Offline Offline

Сообщений: 2812


Просмотр профиля
« : Сентябрь 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. Для чего используются тэги?

ЗЫ: поделитесь, народ, кто как оформляет исходники: чтобы было красиво, удобно, понятно, и на нескольких языках Улыбающийся
« Последнее редактирование: Сентябрь 04, 2009, 12:13 от kuzulis » Записан
ArchLinux x86_64 / Win10 64 bit
UVV
Гость
« Ответ #1 : Сентябрь 04, 2009, 12:26 »
imho, посмотреть в сторону doxygen. И ещё imho, комментарии должны быть только на английском.
Записан
navrocky
Гипер активный житель
*****
Offline Offline

Сообщений: 817


Погроммист


Просмотр профиля
« Ответ #2 : Сентябрь 04, 2009, 12:35 »
А это чей язык разметки комментариев был использован? Местами очень напоминает doxygen.
Записан
Гугль в помощь
UVV
Гость
« Ответ #3 : Сентябрь 04, 2009, 12:38 »
Цитата: navrocky от Сентябрь 04, 2009,  12:35
А это чей язык разметки комментариев был использован? Местами очень напоминает doxygen.
Да, кстати Улыбающийся
Записан
kuzulis
Джедай : наставник для всех
*******
Offline Offline

Сообщений: 2812


Просмотр профиля
« Ответ #4 : Сентябрь 04, 2009, 13:12 »
Цитировать
А это чей язык разметки комментариев был использован? Местами очень напоминает doxygen.
Да, кстати

Мой + чей-то еще + QTшный Улыбающийся
Записан
ArchLinux x86_64 / Win10 64 bit
navrocky
Гипер активный житель
*****
Offline Offline

Сообщений: 817


Погроммист


Просмотр профиля
« Ответ #5 : Сентябрь 04, 2009, 13:34 »
Вопрос не в тему, никто не знает чем qtшники генерят свою красивую документацию?
Записан
Гугль в помощь
BRE
Гость
« Ответ #6 : Сентябрь 04, 2009, 14:11 »
Цитата: navrocky от Сентябрь 04, 2009,  13:34
Вопрос не в тему, никто не знает чем qtшники генерят свою красивую документацию?
http://www.prog.org.ru/topic_7944_0.html
Записан
kuzulis
Джедай : наставник для всех
*******
Offline Offline

Сообщений: 2812


Просмотр профиля
« Ответ #7 : Сентябрь 04, 2009, 15:04 »
Цитировать
imho, посмотреть в сторону doxygen. И ещё imho, комментарии должны быть только на английском.

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

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

Я так думаю, что все-таки можно оформлять исходники с описанием на нескольких языках - но как-то тэгами давать понять Doxygen что ему выбирать (какие из описаний) при генерировании документации!!!  Но я что-то не нашел пока тэгов, отвечающих за это.
Записан
ArchLinux x86_64 / Win10 64 bit
UVV
Гость
« Ответ #8 : Сентябрь 04, 2009, 16:07 »
Я имел ввиду в принципе.
Записан
lit-uriy
Джедай : наставник для всех
*******
Offline Offline

Сообщений: 3880


Просмотр профиля WWW
« Ответ #9 : Сентябрь 04, 2009, 17:10 »
>>И ещё imho, комментарии должны быть только на английском.
>>Я имел ввиду в принципе.
В принципе коментарии должны быть:
1) На своём родном, если ты уважаешь себя и свой язык.
2) Если тебе за коментарии платят, то на том языке за который платят.
3) Если тебе за коментарии не платят, но ты надешся кому-то угодить, то на том языке, для кого пытаешся угодить.
Записан
Юра.
Rcus
Гость
« Ответ #10 : Сентябрь 04, 2009, 17:38 »
Мне кажется что документацию и на одном языке то сложно держать актуальной, а на двух и подавно (и более полезными все равно оказываются более общие описания работы системы, форматов данных и подобное в отдельном документе)
Первый способ который можно попробовать это параметризованные альясы file://///usr/share/doc/doxygen/html/custcmd.html (apt-get install doxygen-doc Веселый)
Второй способ - держать полные копии, управлять генерацией через препроцессор.
Кстати OUTPUT_LANGUAGE влияет только на язык констант в доках.

UPD: Не дописал первый способ. В общем идея в том что имеется два конфигурационных файла, альясы на ненужные языки раскрываются в пустые выражения, на нужные - в абзацы
« Последнее редактирование: Сентябрь 04, 2009, 17:40 от Rcus » Записан
kuzulis
Джедай : наставник для всех
*******
Offline Offline

Сообщений: 2812


Просмотр профиля
« Ответ #11 : Сентябрь 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 ждем чо ответят Улыбающийся
« Последнее редактирование: Сентябрь 05, 2009, 13:52 от kuzulis » Записан
ArchLinux x86_64 / Win10 64 bit
kuzulis
Джедай : наставник для всех
*******
Offline Offline

Сообщений: 2812


Просмотр профиля
« Ответ #12 : Сентябрь 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

Оказывается все просто! Улыбающийся
Записан
ArchLinux x86_64 / Win10 64 bit
Igors
Джедай : наставник для всех
*******
Offline Offline

Сообщений: 11445


Просмотр профиля
« Ответ #13 : Сентябрь 05, 2009, 16:00 »
Цитата: lit-uriy от Сентябрь 04, 2009,  17:10
В принципе коментарии должны быть:
1) На своём родном, если ты уважаешь себя и свой язык.
Видимо так же думал один испанский программист чью программу мне пришлось однажды переделывать. Он много писал о какой-то "perdida" а я никак не мог понять что это  Улыбающийся  С кириллицей хуже, ее у заказчика может просто не быть. Так что при всем уважении к нашему языку, plain English - оптимальный вариант.

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

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

Записан
BRE
Гость
« Ответ #14 : Сентябрь 05, 2009, 16:14 »
Цитата: Igors от Сентябрь 05, 2009,  16:00
В реальном проекте (без open sources) каждый день 5-10 новых функций появляется и столько же убивается. Охота возиться с примечаниями для каждой пропадает очень быстро.
IMHO!
Это для "реального" проекта с количеством участников == 1 (и то позднее вернуться к проекту без документации значительно сложнее чем с документацией).
Если участников > 1, то без нормальной документации развивать и сопровождать проект становиться невозможно.

Если каждый день убивается 5-10 функций:
* для проекта с количеством участников == 1 - нужно учится проектировать;
* для проекта с количеством участников > 1 - нужно увольнять архитектора.
Записан
Страниц: [1] 2 3   Вверх
  Печать  
« предыдущая тема следующая тема »
 
Перейти в:  


Страница сгенерирована за 0.051 секунд. Запросов: 22.