Тут у меня вот какой вопросик назрел - многоуважаемые скриптописатели, а не сталкивались ли вы с проблемой когда написанные вами скрипты разростаются и становятся настолько сложными, что просто требуют создания некоторого рода технической документации ? Поясню : скрипт имеет широкую функциональность и как следствие сложную структуру взаимосвязей функций и пользовательских объектов, система эта настолько сложна, что держать ее в голове постоянно становится очень сложно и без некоторого документирования приходится тяжело(и одними коментами тут не отделаешься). Однако на деле оказывается, что само документирование тоже представляет собой некоторого рода труднсть. Я пробовал многие способы, начиная от квадратиков на листке бумаги, заканчивая Visio и всякими средствами UML моделирования. Однако как мне кажется это не совсем то, так как сам язык js не имеет строгой ярковыраженной объектной структруры, по этому создавать модели для скриптов описанными выше средствами не так то просто. А как вы решаете подобную проблему?
Вы используете устаревший браузер. Этот и другие сайты могут отображаться в нем неправильно.
Необходимо обновить браузер или попробовать использовать другой.
Необходимо обновить браузер или попробовать использовать другой.
Документирование сложных проэктов. Как?
- Автор темы Sakharovich
- Дата начала
- Статус
- Закрыто для дальнейших ответов.
- Сообщения
- 61
- Реакции
- 0
Ответ: Документирование сложных проэктов. Как?
А этот продукт работает под WinXP? Чет в гугле вижу только под Linux. Но мне кажется что это как раз для строго структурированых языков программирования. Со скриптами не тот случай. Но попробоваьт все равно стоит, найду - посморим получится или нет . Спасибо.
А этот продукт работает под WinXP? Чет в гугле вижу только под Linux. Но мне кажется что это как раз для строго структурированых языков программирования. Со скриптами не тот случай. Но попробоваьт все равно стоит, найду - посморим получится или нет . Спасибо.
Ответ: Документирование сложных проэктов. Как?
На мой взгляд с этим дело дрянь... ;-) Давным давно, лет этак 15-20 назад мы занимались очень большим проектом (более 10000 строк кода на фортране и С). Нас было трое и каждый занимался своим куском, так вот, когда код еще малость подрос, мы все пришли к выводу, что никто из нас точно не знает как работает его кусок... ;-))))) Не говоря уже о том, что никто из нас не ведал как работает система в целом... ;-) Еще я читал у кого-то из умных, типа Поста, или кого-то еще, что при увеличении проекта всегда наступает такой момент, что никто из его создателей не может точно сказать, что будет делать программа в данной конкретной ситуации. С этим, на мой взгляд, надо просто жить, пытаясь отлавливать баги по мере их поступления. ;-) Кстати, все производители больших проектов всегда набирают кучу кодеров, каждый из которых отвечает за свои, как я понимаю, не такие уж и огромные куски. Все это, конечно же, мое IMHO и находится скорее в области философии, чем в области решений вопроса, но поскольку я сталкивался с такой проблемой - счел нужным высказаться... ;-)
AirGraph.
На мой взгляд с этим дело дрянь... ;-) Давным давно, лет этак 15-20 назад мы занимались очень большим проектом (более 10000 строк кода на фортране и С). Нас было трое и каждый занимался своим куском, так вот, когда код еще малость подрос, мы все пришли к выводу, что никто из нас точно не знает как работает его кусок... ;-))))) Не говоря уже о том, что никто из нас не ведал как работает система в целом... ;-) Еще я читал у кого-то из умных, типа Поста, или кого-то еще, что при увеличении проекта всегда наступает такой момент, что никто из его создателей не может точно сказать, что будет делать программа в данной конкретной ситуации. С этим, на мой взгляд, надо просто жить, пытаясь отлавливать баги по мере их поступления. ;-) Кстати, все производители больших проектов всегда набирают кучу кодеров, каждый из которых отвечает за свои, как я понимаю, не такие уж и огромные куски. Все это, конечно же, мое IMHO и находится скорее в области философии, чем в области решений вопроса, но поскольку я сталкивался с такой проблемой - счел нужным высказаться... ;-)
AirGraph.
- Сообщения
- 61
- Реакции
- 0
Ответ: Документирование сложных проэктов. Как?
Ваше мнение, пусть даже IMHO, имеет большое значение, так что в след раз пусть вас не терзают сомнения ... , собственно для этого все мы тут собрались ( в большей степени все ). Что же касается темы : ситуация критична, код растет с геометрической прогрессией, и все усугубляется тем что над проэктом я работаю один. Все дошло до того что я сам забываю как работают мной написаные процедуры, бумажки ,схемы карандашем - все это быстро становится безполезным. А в перспективе придется еще и поддерживать пользователей готового продукта ... в общем мысли об этом просто пугают. Есть такой продукт PowerDesigner 10(Sybase). В целом отличный инструмент моделирования широкого спектра информационных структур и потоков, однако на практике оказывается настолько сложным что для оперативного, своевременного моделирования разрабатываемого проэкта необходим специалист по моделированию, работа которого бы только и заключалась в моделировании кода создаваемого кодерами. Кароче дело и правда - дрянь ...
Ваше мнение, пусть даже IMHO, имеет большое значение, так что в след раз пусть вас не терзают сомнения ... , собственно для этого все мы тут собрались ( в большей степени все ). Что же касается темы : ситуация критична, код растет с геометрической прогрессией, и все усугубляется тем что над проэктом я работаю один. Все дошло до того что я сам забываю как работают мной написаные процедуры, бумажки ,схемы карандашем - все это быстро становится безполезным. А в перспективе придется еще и поддерживать пользователей готового продукта ... в общем мысли об этом просто пугают. Есть такой продукт PowerDesigner 10(Sybase). В целом отличный инструмент моделирования широкого спектра информационных структур и потоков, однако на практике оказывается настолько сложным что для оперативного, своевременного моделирования разрабатываемого проэкта необходим специалист по моделированию, работа которого бы только и заключалась в моделировании кода создаваемого кодерами. Кароче дело и правда - дрянь ...
Ответ: Документирование сложных проэктов. Как?
Еще раз повторюсь, попробуйте doxygen, пишите комментарии в коде.
Называйте методы не a, b, c, а осмысленно, DoSomething, SetSomeValue и т.д.
Да, это занимает некоторое время, но оно с лихвой окупается.
И код читать будет проще и при необходимости можно будет догадаться что делает код, без заглядывания в само тело.
Пример кода, комментариев и документации сгенерированной doxygen
Код, взято из Adobe InDesing/InCopy SDK:
Сгенерированная документация:
Еще раз повторюсь, попробуйте doxygen, пишите комментарии в коде.
Называйте методы не a, b, c, а осмысленно, DoSomething, SetSomeValue и т.д.
Да, это занимает некоторое время, но оно с лихвой окупается.
И код читать будет проще и при необходимости можно будет догадаться что делает код, без заглядывания в само тело.
Пример кода, комментариев и документации сгенерированной doxygen
Код, взято из Adobe InDesing/InCopy SDK:
PHP:
/** Copies the specified text into the WideString.
@param position Copy the word that contains this index
@param length How many characters should be copied
@param copy must be non-nil. Is set to the text specified
@return Returns position
*/
virtual TextIndex CopyText(TextIndex position, int32 length, WideString *copy) const = 0;Сгенерированная документация:
PHP:
virtual TextIndex CopyText ( TextIndex position,
int32 length,
WideString * copy
) const [pure virtual]
Copies the specified text into the WideString.
Parameters:
position Copy the word that contains this index
length How many characters should be copied
copy must be non-nil. Is set to the text specified
Returns:
Returns positionОтвет: Документирование сложных проэктов. Как?
Полностью согласен со Strizh по поводу использования осмысленных идентификаторов. Код становится самодокументированным. Чем точнее смысл идентификатора - тем лучше. А вот что касается комментариев, то считаю их делом вкуса. Лично я ими не пользуюсь. Если идентификаторы осмысленны, то код говорит сам за себя, а комментарии сильно удлиняют и без того здоровенные файлы исходного текста, в которых становится трудно найти необходимый кусок. По части комментариев я совершенно согласен с упомянутым мной Постом, который утверждал, что настоящие программисты с удовольствием потратят 2-3 рабочих дня для того, чтобы сэкономить 5 наносекунд внутри очень короткого цикла, а комментарии оставят на потом... ;-))))))
Еще могу посоветовать тратить значительное время на саму постановку задачи и планирование структуры проекта. Чем детальнее проработана структура методов, функций и т.п. на начальном этапе, тем короче получится результирующий код и, как следствие, он будет более понятен даже по истечении значительного промежутка времени.
AirGraph.
Полностью согласен со Strizh по поводу использования осмысленных идентификаторов. Код становится самодокументированным. Чем точнее смысл идентификатора - тем лучше. А вот что касается комментариев, то считаю их делом вкуса. Лично я ими не пользуюсь. Если идентификаторы осмысленны, то код говорит сам за себя, а комментарии сильно удлиняют и без того здоровенные файлы исходного текста, в которых становится трудно найти необходимый кусок. По части комментариев я совершенно согласен с упомянутым мной Постом, который утверждал, что настоящие программисты с удовольствием потратят 2-3 рабочих дня для того, чтобы сэкономить 5 наносекунд внутри очень короткого цикла, а комментарии оставят на потом... ;-))))))
Еще могу посоветовать тратить значительное время на саму постановку задачи и планирование структуры проекта. Чем детальнее проработана структура методов, функций и т.п. на начальном этапе, тем короче получится результирующий код и, как следствие, он будет более понятен даже по истечении значительного промежутка времени.
AirGraph.
Ответ: Документирование сложных проэктов. Как?
Да, "Преждевременная оптимизация - корень всех бед в программировании", да, "Гораздо, гораздо проще сделать корректную программу быстрой, чем быструю - корректной" (Рекомендация 8. Не оптимизируйте преждевременно).
AirGraph сказал(а):что настоящие программисты с удовольствием потратят 2-3 рабочих дня для того, чтобы сэкономить 5 наносекунд внутри очень короткого цикла, а комментарии оставят на потом... ;-))))))
Да, "Преждевременная оптимизация - корень всех бед в программировании", да, "Гораздо, гораздо проще сделать корректную программу быстрой, чем быструю - корректной" (Рекомендация 8. Не оптимизируйте преждевременно).
Ответ: Документирование сложных проэктов. Как?
А вот и для JS нашел "документатор".
По сути использует тот же синтаксис что и doxygen. Нужен perl и еще какая-то зависимость. При желании за 10 минут можно разобраться. Сам не пробовал.
А вот и для JS нашел "документатор".
По сути использует тот же синтаксис что и doxygen. Нужен perl и еще какая-то зависимость. При желании за 10 минут можно разобраться. Сам не пробовал.
Ответ: Документирование сложных проэктов. Как?
Прошу прощения, но Пост не сравнивал быстроту с корректностью. Да, речь шла об оптимизации, но не о своевременной или нет, а об оптимизации взамен написания комментариев. Вам не кажется?.. ;-)
AirGraph.
Strizh сказал(а):Да, "Преждевременная оптимизация - корень всех бед в программировании", да, "Гораздо, гораздо проще сделать корректную программу быстрой, чем быструю - корректной" (Рекомендация 8. Не оптимизируйте преждевременно).
Прошу прощения, но Пост не сравнивал быстроту с корректностью. Да, речь шла об оптимизации, но не о своевременной или нет, а об оптимизации взамен написания комментариев. Вам не кажется?.. ;-)
AirGraph.
Ответ: Документирование сложных проэктов. Как?
- Каков ваш выбор, оптимизация на 2-3 мс метода, выполняющегося 200 мс или написание коммента к этому методу?
Все выбрали коммент. Вопрос об оптимизации вынесли бы в коммент в виде TODO на будущее, в случае такой необходимости.
Пробежался я по офису, опросил пару джавистов и пару С++ программеров с вопросом:AirGraph сказал(а):Прошу прощения, но Пост не сравнивал быстроту с корректностью. Да, речь шла об оптимизации, но не о своевременной или нет, а об оптимизации взамен написания комментариев. Вам не кажется?.. ;-)
AirGraph.
- Каков ваш выбор, оптимизация на 2-3 мс метода, выполняющегося 200 мс или написание коммента к этому методу?
Все выбрали коммент. Вопрос об оптимизации вынесли бы в коммент в виде TODO на будущее, в случае такой необходимости.
- Сообщения
- 61
- Реакции
- 0
Ответ: Документирование сложных проэктов. Как?
Я что то не совсем понял причем тут оптимизация на 2 нс и коментарий, js, интерпритатор игнорирует коменты, может конечно и тратит на это некоторое время но в рамках форума такие потери несущественны, а коментарий писать это никогда нелишнее, в голове держать всё написанное сложно, выход описывать наводящими коментами в таком случае можно смело все забывать, потому что при необходимости раз взглянул и все понятно. А вот с чем я полностью согласен так это с идеей грамотной системы имен переменных, методов, функций, и т.п. оч помогает, но иногда и комент добавить нужно. Ведь пару строк комента сейчас экономят пару часиков времени потом, потраченых на осмысление кода. Но документация нужна ( я про тему ), не для облегчения восстановления алгоритмов, а для оптимизации самого процесса проэктирования. Все таки намного легче когда оперируешь не прямоугольничками на бумаге, нарисованными от руки, а некоторыми формами, со описанными свойствами и все такое .
Я что то не совсем понял причем тут оптимизация на 2 нс и коментарий, js, интерпритатор игнорирует коменты, может конечно и тратит на это некоторое время но в рамках форума такие потери несущественны, а коментарий писать это никогда нелишнее, в голове держать всё написанное сложно, выход описывать наводящими коментами в таком случае можно смело все забывать, потому что при необходимости раз взглянул и все понятно. А вот с чем я полностью согласен так это с идеей грамотной системы имен переменных, методов, функций, и т.п. оч помогает, но иногда и комент добавить нужно. Ведь пару строк комента сейчас экономят пару часиков времени потом, потраченых на осмысление кода. Но документация нужна ( я про тему ), не для облегчения восстановления алгоритмов, а для оптимизации самого процесса проэктирования. Все таки намного легче когда оперируешь не прямоугольничками на бумаге, нарисованными от руки, а некоторыми формами, со описанными свойствами и все такое .
- Сообщения
- 61
- Реакции
- 0
Ответ: Документирование сложных проэктов. Как?
Разумное преджложение! Говоря о документации я прежде всего имею ввиду создание в процессе разработки \ проэктирования \ реализации некой модели, отображающей структуру проэкта в целом, модель эта предпологает некоторый уровень абстракции для обеспечения связи между реальной архитектурой проэкта и концепцией разработок. Кроме того так же важным условием приемлемого процесса документирования является его оперативность и доступность анализа созданых компонентов. ТОлько что наткнулся на инструмент под названием doc-o-matic 5. Работает под виндой, не требует особой процедуры сборки, принцип работы - wysiwyg. Простой но в тоже время в перечне языков на которые он ориентирован имеется и JS. Пока что предварительно ознакомляюсь.
Разумное преджложение! Говоря о документации я прежде всего имею ввиду создание в процессе разработки \ проэктирования \ реализации некой модели, отображающей структуру проэкта в целом, модель эта предпологает некоторый уровень абстракции для обеспечения связи между реальной архитектурой проэкта и концепцией разработок. Кроме того так же важным условием приемлемого процесса документирования является его оперативность и доступность анализа созданых компонентов. ТОлько что наткнулся на инструмент под названием doc-o-matic 5. Работает под виндой, не требует особой процедуры сборки, принцип работы - wysiwyg. Простой но в тоже время в перечне языков на которые он ориентирован имеется и JS. Пока что предварительно ознакомляюсь.
- Сообщения
- 61
- Реакции
- 0
Ответ: Документирование сложных проэктов. Как?
Что касается коментов - то они не позволяют взглянуть на проэкт в целом, а при глобальном проэктировании именно это и требуется. Что касается jsDoc и Oxygen - я начал с jsDoc, однако внешние источники порекомендовали doc-omatic, как я уже говорил - имеет дружественный интерфейс и просто у становке, эт пока что все что могу сказать.
Что касается коментов - то они не позволяют взглянуть на проэкт в целом, а при глобальном проэктировании именно это и требуется. Что касается jsDoc и Oxygen - я начал с jsDoc, однако внешние источники порекомендовали doc-omatic, как я уже говорил - имеет дружественный интерфейс и просто у становке, эт пока что все что могу сказать.
Ответ: Документирование сложных проэктов. Как?
Невыдержал. Решил вставить свое мнение.
Могу ошибатся, но перед разработкой проэкта немешалобы нарисовать все структуры и взаимодействие модулей. Если это проблемотично, то не слишком ли широкомаштабный проэкт затеян. Могет кто нить разробатывает аналог Винды на JS.
И что значит "широкую функциональность"?
Невыдержал. Решил вставить свое мнение.
Могу ошибатся, но перед разработкой проэкта немешалобы нарисовать все структуры и взаимодействие модулей. Если это проблемотично, то не слишком ли широкомаштабный проэкт затеян. Могет кто нить разробатывает аналог Винды на JS.
И что значит "широкую функциональность"?
- Сообщения
- 61
- Реакции
- 0
Ответ: Документирование сложных проэктов. Как?
Первое : на практике редко бывает так что бы результат предварительного мозгового штурма по теме реализаций расплывчатых требований клиента(а именно это и есть "структуры и взаимодействие модулей"), соответствовал основной линии разработки и в дальнейшем. Зачастую Проэкт( в смысле план разработки ) и сам процесс разработки(точнее его направление) взаимодействуют друг с другом изменяя то план на основании методов реализации то методы реализации на основании плана. Т.е. обсолютного слепка с плана в виде результата проэкта не получается( говорю только за себя, ... как минимум ), так вот в такой ситуации только и остается - это создание некой документации в ходе разработки, в которой бы и отражалась ситуация на данный момент.
Касательно же конкретно моего проэкта - то реч идет не о "винде на js", а о некоторой другой системе, а именно инструмент верстки широкого набора изданий типа классифаид, а собственно ""широкая функциональность"" представляет собой набор функций реализующих автоматизацию всех процедур выполняемых при верстке того или иного издания. Вот как раз подобная универсальность и представляет собой причину такой сложности проэкта, и повторюсь : в силу того что я работаю один, мне не хватает оперативной памяти для охвата ВСЕХ модулей - Пользоватльского интерфейса, модуля подключения библиотек функций, основной управляющей части скрипта и т.д. Вот и выходит пока занимаешься одним - что то другое медлено но уверено уползает из памяти, и перечитывать сотни строк кода с коментами вариант не самого оптимального решения, вот и возник вопрос про документирование проэктов. И еще что качается шорокомосштабности - ни о чем таком реч не идет, просто, еще раз повторяю , целый проэкт, держать в одной голове очень сложно. И реч то идет не о количестве строк а о самой внутренней архитектуре приложения.
Первое : на практике редко бывает так что бы результат предварительного мозгового штурма по теме реализаций расплывчатых требований клиента(а именно это и есть "структуры и взаимодействие модулей"), соответствовал основной линии разработки и в дальнейшем. Зачастую Проэкт( в смысле план разработки ) и сам процесс разработки(точнее его направление) взаимодействуют друг с другом изменяя то план на основании методов реализации то методы реализации на основании плана. Т.е. обсолютного слепка с плана в виде результата проэкта не получается( говорю только за себя, ... как минимум ), так вот в такой ситуации только и остается - это создание некой документации в ходе разработки, в которой бы и отражалась ситуация на данный момент.
Касательно же конкретно моего проэкта - то реч идет не о "винде на js", а о некоторой другой системе, а именно инструмент верстки широкого набора изданий типа классифаид, а собственно ""широкая функциональность"" представляет собой набор функций реализующих автоматизацию всех процедур выполняемых при верстке того или иного издания. Вот как раз подобная универсальность и представляет собой причину такой сложности проэкта, и повторюсь : в силу того что я работаю один, мне не хватает оперативной памяти для охвата ВСЕХ модулей - Пользоватльского интерфейса, модуля подключения библиотек функций, основной управляющей части скрипта и т.д. Вот и выходит пока занимаешься одним - что то другое медлено но уверено уползает из памяти, и перечитывать сотни строк кода с коментами вариант не самого оптимального решения, вот и возник вопрос про документирование проэктов. И еще что качается шорокомосштабности - ни о чем таком реч не идет, просто, еще раз повторяю , целый проэкт, держать в одной голове очень сложно. И реч то идет не о количестве строк а о самой внутренней архитектуре приложения.
- Статус
- Закрыто для дальнейших ответов.
Поделиться: