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

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

Страниц: 1 [2] 3   Вниз
  Печать  
Автор Тема: Правильное оформление комментариев, пояснений и документации в исходном коде  (Прочитано 25209 раз)
Igors
Джедай : наставник для всех
*******
Offline Offline

Сообщений: 11445


Просмотр профиля
« Ответ #15 : Сентябрь 05, 2009, 16:37 »

Если каждый день убивается 5-10 функций:
А что здесь удивительного? Если задача, например, перевести UI со старого на тот же Qt - то гораздо больше
* для проекта с количеством участников == 1 - нужно учится проектировать;
Проигнорировано
* для проекта с количеством участников > 1 - нужно увольнять архитектора.
Если он вообще есть. Реальная ситуация (без кавычек): есть 2 программиста а работы/заказов сейчас много. Нужно взять еще одного. Кто будет заниматься архитектурой и .т. п ?
Записан
BRE
Гость
« Ответ #16 : Сентябрь 05, 2009, 16:53 »

Если каждый день убивается 5-10 функций:
А что здесь удивительного? Если задача, например, перевести UI со старого на тот же Qt - то гораздо больше
Я писал о разработке нового приложения.

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

* для проекта с количеством участников > 1 - нужно увольнять архитектора.
Если он вообще есть. Реальная ситуация (без кавычек): есть 2 программиста а работы/заказов сейчас много. Нужно взять еще одного. Кто будет заниматься архитектурой и .т. п ?
Для реального проекта, нужно потратить определенное время (не 15 минут), совместно все спроектировать и задокументировать(!). Определить необходимые сущности, сформировать классы, продумать взаимодействия всех участников системы. Если этого не сделать, то в лучшем случае выйдет одна версия программы, которую в дальнейшем невозможно будет расширять и сопровождать. Если продукт с плохой архитектурой начать расширять,  качество продукта, как правило, начнет ухудшаться, что приведет к уменьшению заказов. Такова жизнь.
Кстати, о важности проектирования, написано уйма книг. И даже хорошо спроектированную систему, без нормального документирования, очень сложно сопровождать.
Попробуй вернуться к своему же проекту этак через год и что-нибудь добавить. Сколько времени тебе понадобиться, что бы вспомнить все нюансы? А с документацией это будет на порядок быстрей.
« Последнее редактирование: Сентябрь 05, 2009, 17:05 от BRE » Записан
BRE
Гость
« Ответ #17 : Сентябрь 05, 2009, 17:02 »

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

Сообщений: 11445


Просмотр профиля
« Ответ #18 : Сентябрь 05, 2009, 17:34 »

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

Ладно, это уже флуд, умолкаю.
Записан
BRE
Гость
« Ответ #19 : Сентябрь 05, 2009, 17:50 »

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

Один упрется рогом что это должно быть только "private" и объявлять friend'ов не моги! Нарушается, дескать, концептуальная чистота.
Вспоминаю как перевернула мое восприятие о ООП книга Гради Буч. Как в голове все стало на свои места и я первый раз постарался отойди от C с использованием классов (а я то думал что уже много лет использую ООП на C++).  Улыбающийся
Записан
Igors
Джедай : наставник для всех
*******
Offline Offline

Сообщений: 11445


Просмотр профиля
« Ответ #20 : Сентябрь 05, 2009, 20:40 »

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

Kuzulis, примите мои извинения за OT.
Записан
BRE
Гость
« Ответ #21 : Сентябрь 05, 2009, 21:04 »

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

Сообщений: 11445


Просмотр профиля
« Ответ #22 : Сентябрь 05, 2009, 21:35 »

Зачем же "радовать" людей, которым придется сопровождать вашу систему лет через 5, отсутствием нормальной документации?
А затем чтобы они знали что такое "держать проект" и глупых иллюзий не имели. И старая дока поможет им "як собацi п'ята нога"
Записан
BRE
Гость
« Ответ #23 : Сентябрь 05, 2009, 22:52 »

А затем чтобы они знали что такое "держать проект" и глупых иллюзий не имели. И старая дока поможет им "як собацi п'ята нога"
Странный какой то спор у нас получается.  Строит глазки
Почему дока должна быть старая, изменился класс (добавили/изменили что-то) - задокументировали. В чем трудности.
Ладно, спорить не хочу, но думаю со временем ты к этому придешь сам или заказчик/начальник будет это требовать от тебя.
Записан
kuzulis
Джедай : наставник для всех
*******
Offline Offline

Сообщений: 2812


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

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

ArchLinux x86_64 / Win10 64 bit
UVV
Гость
« Ответ #25 : Сентябрь 10, 2009, 06:12 »

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

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

В реальном проекте (без open sources)...
А с чего вдруг "реальный проект" не может быть open source?
« Последнее редактирование: Сентябрь 11, 2009, 04:24 от UVV » Записан
Авварон
Джедай : наставник для всех
*******
Offline Offline

Сообщений: 3260


Просмотр профиля
« Ответ #26 : Сентябрь 10, 2009, 21:26 »

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

Сообщений: 11445


Просмотр профиля
« Ответ #27 : Сентябрь 10, 2009, 21:52 »

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

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

Может в названиях/соглашениях немного попутал но все я реально пользовал в разных целях, доволен и оцениваю очень высоко. Другое дело что мои личные шансы на такой крутой open source ...ну как бы это сказать.. не очень велики Улыбающийся Так что я буду писать нормальные рабочие комментарии
Записан
SABROG
Гость
« Ответ #28 : Сентябрь 10, 2009, 21:56 »

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

Имхо это как раз тот случай, когда "богатство" русского языка служит дурную службу. Я конечно не против перевода английской документации на русский, но лишь с той целью, чтобы люди изучавшие язык отличный от английского могли начать программировать и изучать английский.
Записан
UVV
Гость
« Ответ #29 : Сентябрь 11, 2009, 04:21 »

покажите нормальный опенсорс проект:) всякие k3b/амарок/миранда в счет не идут - слишком мелко
А форум по какой библиотеке вообще? =)
Она, вдруг, стала closed source??
Записан
Страниц: 1 [2] 3   Вверх
  Печать  
 
Перейти в:  


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