Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Знаешь мы эту проблему довольно просто решили. Есть ребенок (почти бесплатный), который документирует все доксигеном (сам лазает по исходникам) и пишет описание, включая примеры использования и неявные предположения, в вордпрессовский блог. Почему блог а не вики? Хз, меня это не волновало, а инициатор такого процесса вики не любит почему-то.
Плюсов несколько. Во-первых, все обязаны писать так, чтобы ребенок понял. Если ребенок не понял, то ребенку следует объяснить.Во-вторых, появляется довольно полная документация, описанная хорошим языком. Ребенок также обязан писать чтобы все его понимали,без особого выпендрежа, но так, чтобы читать было не скучно. Минус только один -- через год ребенок начинает писать нормально, через два сваливает.
Здравствуйте, minorlogic, Вы писали:
M>>> Насчет высокоуровневости не соглашусь, грамотное структкрирование не усложняет высокоуровневые сущности и функционал. AVK>>Хм, не уловил противоречия с тем, что сказал я.
M>"Чем высокоуровневей концепция, тем менее ее видно из голого кода." с этим.
Именно. Это никак не говорит о том, что "грамотное структкрирование усложняет высокоуровневые сущности и функционал".
M>Это не всегда так, а задача програмиста делать чтобы это всегда было не так.
Это практически всегда так, по одной простой причине: компилируемый код обязан быть предельно подробен и детален.
M>>>Хорошее соременное направление это потдержка IDE стандартных коментариев. AVK>>Какая именно поддержка? M>Подсветка коментариев для переменных, функций, классов и т.п. (хинты)
В смысле?
M>Автогенерация заглушек для коментариев.
Ну, это какая то смешная мелочь, ИМХО.
M>Контроль за соответствием коментариев и кода.
Это все уже есть.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
VD>>Ты нам скажи... Это ты для решарпера что-то обдумываешь или так по трепаться охота?
AVK>Ты же понимаешь, на этот вопрос я тебе не отвечу.
Не понимаю. Более того считаю это маразмом. Одно дело разговор о возможностях IDE, и совсем другое общий разговор. Если хочешь получить внятный ответ, то задавай внятные границы обсуждения.
К тому же даже из этого ответа уже ясно, что для решарпера.
VD>> Т.е. ты об автоматизации процесса в идеале, или о самом процессе?
AVK>И о том, и о другом.
Если речь об "вообще", то я бы начал с того, что процесс разработки — это технология в кторой написание кода, его отладка, написание документации и т.п. — всего лишь часть этого процесса.
Лично я часто прежде чем писать сложный момент некой софтины или саму софтину начинаю с того, что пишу некое описание того что я хочу достигнуть. Это описание в процессе разработки неизменно меняется. К сожалению в большинстве случаев это описание выбрасывается (в виду того, что рано или поздно начинает отставать от жизни или просто потому, что на его поддержание нужно тратить силы которых нет). А это и есть часть того что могло бы стать как документацией, так и неким центром навигации по коду проекта.
Если уж задумываться об документировании, то нужно задуматься о создании некой системы разработки проекта которая вела бы от наброска плана, к созданию каркаса проекта и к его детализации и трансформации. Итогом работы такой системы и будет как само ПО, так и документация по проекту.
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, VladD2, Вы писали:
VD>Поступи очень просто... Попробуй написать полноценную документацию к Решарперу или хотя бы к Янусу, тогда тебе сразу станет все очевидно.
Думаешь, я никогда этим не занимался? У меня есть собственные идеи и мысли, во многом совпадающие с тем, что тут уже написали.
Однако, интересно мнение общественности — одна голова хорошо, а много — лучше.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
AVK>Думаешь, я никогда этим не занимался? У меня есть собственные идеи и мысли, во многом совпадающие с тем, что тут уже написали.
Думаю, что в реальных масштабах не занимался. Иначе бы вопрос для тебя был бы очевидным.
К тому же одно дело когда ты что-то когда-то делал, а другое когда ты делаешь продукт для собственного использования.
AVK>Однако, интересно мнение общественности — одна голова хорошо, а много — лучше.
Сколько людей столько и мнений. К тому же большая часть респондентов серьезно документацией не занимается.
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, VladD2, Вы писали:
AVK>>Думаешь, я никогда этим не занимался? У меня есть собственные идеи и мысли, во многом совпадающие с тем, что тут уже написали.
VD>Думаю, что в реальных масштабах не занимался.
Не угадал.
VD> Иначе бы вопрос для тебя был бы очевидным.
Для меня подобные вопросы в принципе не могут быть очевидными, слишком они сложные и многофакторные. Даже в рамках одного языка и одной IDE методики и методологии, набор требований и т.п. могут варьироваться широчайшим образом.
AVK>>Однако, интересно мнение общественности — одна голова хорошо, а много — лучше.
VD>Сколько людей столько и мнений. К тому же большая часть респондентов серьезно документацией не занимается.
Тем не менее.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
У меня уже давно есть идея, правда так до сих пор и не реализованная Даже где-то на форуме высказывал какие-то отдельные мысли...
Документация должна быть интерактивной. Это значит, что всякие доксигены генерируют статическую документацию на основе комментариев, а нужна система, которая ничего бы не генерировала, а позволяла бы работать с документацией прямо из IDE. Т.е. можно было бы вывести документацию, просто ткнув мышью в непонятное место в программе; перемещаться по гиперссылкам; искать разными способами — по контексту, по тегам, по автору, дате и т.д.; максимально быстро, в один щелчек мыши, переходить от кода к связанной с ним документации, и обратно; редактировать документацию прямо из IDE в удобном визуальном редакторе. Система управления документацией должна проверять целостность документации, автоматически находить незадокументированные части кода; части, для которых дата обновления документации меньше даты обновления кода; и т.д.
Документация должна быть интегрирована в систему контроля версий, в багтрекер и систему планирования (т.е., по сути, это уже не классическая "документация", а некая база знаний, "навешенная" на solution с кодом и максимально тесно интегрированная с ним);
Вариантов реализцаии может быть много, но в целом за основу должна быть взята идея "древовидного редактора" (аутлайнера)
Где-то сбоку появляется панель, аналогичная Solution Explorer, в которой в виде иерархического дерева представлена вся документация системы. Ведь документация бывает не только к классам и методам, но и "оторванная" от кода — объясняющая предметную область, особенности сборки проектов и т.д. Поэтому разные узлы дерева должны иметь разные способы связи с кодом. Хорошее решение — иметь один файл документации на один файл исходника, имя файла такое же, а расширение другое.
Также должна быть как минимум еще одна панель — визуальный вьюер/редактор документации (на примере Visual Studio — удобно было бы иметь ее внизу, там где Output, Error List и т.д.). Также, должна быть возможность открытия файлов документации не в панели, а в обычных окнах редактора (на случай если документация большая).
Кроме текстовых (точнее, html) файлов, удобно было бы иметь файлы других типов, в особенности — "диаграммы в свободном стиле" (смесь UML, MindMaps, блок-схем и т.д.).
Документация должна храниться в простых html и xml файлах (а не в единой базе, как это делается во всех аутлайнерах), чтобы разные программисты могли редактировать ее одновременно, и затем независимо друг от друга вносить в систему контроля версий.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Внесу свои 5 копеек.
Несколько навеяно этим
.
В последнее время очень неплохо развились системы документирования классов, методов и полей, автоматическая генерация доков по описанию, отображение документации метода в IDE по наведению мыши и т.п. То есть в принципе можно достаточно сносно документировать API и удобно пользоваться(кстати, в этом смысле гораздо больше javadoc'ов и c# xml comment'ов мне нравится формат документирования в Fantom, так как отлично читается и без 'компиляции' в какой-нибудь rich text)Однако зачастую этого все же недостаточно — имеет смысл документировать и тело методов, а там, собственно, ничего не поменялось — // или /**/ в зубы и с plain text'ом на амбразуру. Возможно это оправдано, но иногда хочется и большего.
Еще несколько соображений:
— Где бы мы ни хранили документацию, в коде или рядом, она должна быть в виде 'исходников', типа wiki markup, чтобы можно было делать diff
— Опять же независимо от места хранения, IDE должна уметь показывать/скрывать документацию непосредственно в коде
— Во время компиляции должна проверяться целостность документации (отсутствие битых ссылок на код) и показываться в виде как минимум warning'ов
<q>Это значит, что всякие доксигены генерируют статическую документацию на основе комментариев</q>
Доксигены, к сожалению, генерируют документацию только для API. Они под это заточены. Многочисленные попытки приспособить доксиген и прочие natural docs для комментирования программ провалились.
<q>а нужна система, которая ничего бы не генерировала, а позволяла бы работать с документацией прямо из IDE. Т.е. можно было бы вывести документацию, просто ткнув мышью в непонятное место в программе;</q>
Серьезная проблема в связи кода и документации. Как показывает практика, малейший рефакторинг такую связь рвет, как оркский герой Тузик саблезадого тигра Грелку .
<q>Система управления документацией должна проверять целостность документации, автоматически находить незадокументированные части кода; части, для которых дата обновления документации меньше даты обновления кода; и т.д.</q>
Сможете реализовать — и до конца своих дней будете отдыхать на канарах . Пока ни у кого не получилось .
<q>Вариантов реализцаии может быть много, но в целом за основу должна быть взята идея "древовидного редактора"</q>
Это не реализация, это внешний вид самой простой части. Поверьте старику на слово, реализовать текстовый редактор любого форм-факторы — это очень простая задача. А вот как связать документацию с кодом чтобы всем было удобно и не рассыпалось через месяц — это основная проблема в данном вопросе. Я уже года четыре над этим работаю, результаты пока малоудовлетворительные . У остальных (silk edit сотоварищи) тоже ничего пока не получилось.
Здравствуйте, Eye of Hell, Вы писали:
EOH>Серьезная проблема в связи кода и документации. Как показывает практика, малейший рефакторинг такую связь рвет, как оркский герой Тузик саблезадого тигра Грелку .
Существует несколько способов решения: или привязка тегов документации к именам классов и функций; или использование специальных комментариев-ссылок на документацию. Сейчас я склоняюсь к первому способу. При этом в коде вообще не содержится никакой документации. Можно для операции Compile любого файла добавить вызов внешней тулзы, которая парсила бы файл до уровня имен методов, и проверяла бы соответствие информации из документации и информации.
EOH>Система управления документацией должна проверять целостность документации, автоматически находить незадокументированные части кода; части, для которых дата обновления документации меньше даты обновления кода; и т.д. EOH>Сможете реализовать — и до конца своих дней будете отдыхать на канарах . Пока ни у кого не получилось .
Если смогу, то скорее всего, просто открою для всеобщего бесплатного использования. Не умею я деньги на этом зарабатывать
Тут главная проблема — отслеживать изменения в отдельных фрагментах кода. Теоретически можно каждый раз просчитывать какие-то контрольные суммы от значащих символов для каждого метода и хранить их в xml-файле, а при несовпадении предыдущей и текущей сумм помечать метод в базе как "измененный".
EOH>Это не реализация, это внешний вид самой простой части. Поверьте старику на слово, реализовать текстовый редактор любого форм-факторы — это очень простая задача. А вот как связать документацию с кодом чтобы всем было удобно и не рассыпалось через месяц — это основная проблема в данном вопросе. Я уже года четыре над этим работаю, результаты пока малоудовлетворительные . У остальных (silk edit сотоварищи) тоже ничего пока не получилось.
А можно поинтересоваться подробностями вашей работы?
Существует несколько способов решения: или привязка тегов документации к именам классов и функций; или использование специальных комментариев-ссылок на документацию. Сейчас я склоняюсь к первому способу. При этом в коде вообще не содержится никакой документации. Можно для операции Compile любого файла добавить вызов внешней тулзы, которая парсила бы файл до уровня имен методов, и проверяла бы соответствие информации из документации и информации.
Первый способ подразумевает несколько вещей. Во-первых, это парсинг исходников. Для языков с поддержкой reflection (C# сотоварищи) это сделать достаточно просто, но что Вы будете делать со всеми остальными? Поверьте, распарсить .cpp файл — та еще задача, авторы Visual Assist, не самые плохие программисты, уже много лет над ней бьются и не могу сказать что у них все получается. Во-вторых, это рефакторинг. Как система работы с комментариями определит, что имя метода или функции поменялось? Тут нужна поддержка IDE. Причем не одной. А что делать с изменениями во время diff/merge? С комментариями к блокам кода внутри методов?
А можно поинтересоваться подробностями вашей работы?
А что именно Вас интересует? На данный момент реализовано code review и ведутся работы над model driven development. И то и другое делается через добавление в код меток. GUID'ы для code review, комментарии определенного формата для генерации модели из кода и обновления кода из модели. Практически реализовал только как аддоны к Visual Studio для языка C++.
.