Здравствуйте, AndrewVK, Вы писали:
VD>>Ты нам скажи... Это ты для решарпера что-то обдумываешь или так по трепаться охота?
AVK>Ты же понимаешь, на этот вопрос я тебе не отвечу.
Не понимаю. Более того считаю это маразмом. Одно дело разговор о возможностях IDE, и совсем другое общий разговор. Если хочешь получить внятный ответ, то задавай внятные границы обсуждения.
К тому же даже из этого ответа уже ясно, что для решарпера.
VD>> Т.е. ты об автоматизации процесса в идеале, или о самом процессе?
AVK>И о том, и о другом.
Если речь об "вообще", то я бы начал с того, что процесс разработки — это технология в кторой написание кода, его отладка, написание документации и т.п. — всего лишь часть этого процесса.
Лично я часто прежде чем писать сложный момент некой софтины или саму софтину начинаю с того, что пишу некое описание того что я хочу достигнуть. Это описание в процессе разработки неизменно меняется. К сожалению в большинстве случаев это описание выбрасывается (в виду того, что рано или поздно начинает отставать от жизни или просто потому, что на его поддержание нужно тратить силы которых нет). А это и есть часть того что могло бы стать как документацией, так и неким центром навигации по коду проекта.
Если уж задумываться об документировании, то нужно задуматься о создании некой системы разработки проекта которая вела бы от наброска плана, к созданию каркаса проекта и к его детализации и трансформации. Итогом работы такой системы и будет как само ПО, так и документация по проекту.
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, AndrewVK, Вы писали:
C>>Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki. AVK>А наоборот?
Тоже надо, но смысла меньше. Скорее подойдёт простой обратный индекс. Типа "кто ссылается на меня из кода".
C>> Куда можно было бы вставлять схемы, рисунки, screenshot'ы. AVK>Куда, в код? А редактировать как?
В wiki.
Т.е. в коде ты пишешь _только_ текст. Если нужно что-то с rich text formatting или картинками — ставишь специальный комментарий, ссылающийся на wiki-статью, в которую уже можно вставить графики и вообще другие элементы.
Может выглядеть так, пишем:
public void veryComplexMethod()
{
....
//Тут понимаем, что у нас всё слишком сложно и нужно бы это задокументировать.
//Жмём, скажем, ctrl-i.
}
Автоматически создаётся статья "SomeClass_veryComplexMethod", открывается во всплывающем окне/новом табе/панели, а в методе прописывается на неё ссылка:
Если IDE умная, то она заменить комментарий @has_wiki на графическое изображение статьи (если оно небольшое). Возможно ещё имеет смысл сделать inline-редактирование.
В общем, смысл в том, чтоб не требовалось отвлекаться на поиск документации по коду, чтобы документация его не захламляла, и чтобы код оставить чистым текстом.
C>>И чтоб компилятор проверял битые ссылки. AVK>Именнно компилятор?
Ну или специальная тулза, не суть важно. Главное, чтобы можно было легко найти, где появились битые ссылки.
C>>И ещё хочу пони. AVK>Это шутка?
Да Но от лошадки всё равно бы не отказался.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
У меня уже давно есть идея, правда так до сих пор и не реализованная Даже где-то на форуме высказывал какие-то отдельные мысли...
Документация должна быть интерактивной. Это значит, что всякие доксигены генерируют статическую документацию на основе комментариев, а нужна система, которая ничего бы не генерировала, а позволяла бы работать с документацией прямо из IDE. Т.е. можно было бы вывести документацию, просто ткнув мышью в непонятное место в программе; перемещаться по гиперссылкам; искать разными способами — по контексту, по тегам, по автору, дате и т.д.; максимально быстро, в один щелчек мыши, переходить от кода к связанной с ним документации, и обратно; редактировать документацию прямо из IDE в удобном визуальном редакторе. Система управления документацией должна проверять целостность документации, автоматически находить незадокументированные части кода; части, для которых дата обновления документации меньше даты обновления кода; и т.д.
Документация должна быть интегрирована в систему контроля версий, в багтрекер и систему планирования (т.е., по сути, это уже не классическая "документация", а некая база знаний, "навешенная" на solution с кодом и максимально тесно интегрированная с ним);
Вариантов реализцаии может быть много, но в целом за основу должна быть взята идея "древовидного редактора" (аутлайнера)
Где-то сбоку появляется панель, аналогичная Solution Explorer, в которой в виде иерархического дерева представлена вся документация системы. Ведь документация бывает не только к классам и методам, но и "оторванная" от кода — объясняющая предметную область, особенности сборки проектов и т.д. Поэтому разные узлы дерева должны иметь разные способы связи с кодом. Хорошее решение — иметь один файл документации на один файл исходника, имя файла такое же, а расширение другое.
Также должна быть как минимум еще одна панель — визуальный вьюер/редактор документации (на примере Visual Studio — удобно было бы иметь ее внизу, там где Output, Error List и т.д.). Также, должна быть возможность открытия файлов документации не в панели, а в обычных окнах редактора (на случай если документация большая).
Кроме текстовых (точнее, html) файлов, удобно было бы иметь файлы других типов, в особенности — "диаграммы в свободном стиле" (смесь UML, MindMaps, блок-схем и т.д.).
Документация должна храниться в простых html и xml файлах (а не в единой базе, как это делается во всех аутлайнерах), чтобы разные программисты могли редактировать ее одновременно, и затем независимо друг от друга вносить в систему контроля версий.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
В полном идеале лучше ьез документирования, чтобы язык позволял максимально ясно передать то что хотел сделать програмист.
Здравствуйте, AndrewVK, Вы писали:
AVK>Здравствуйте, minorlogic, Вы писали:
M>>В полном идеале лучше ьез документирования, чтобы язык позволял максимально ясно передать то что хотел сделать програмист.
AVK>Это нереально, по крайней мере в ближайшем будущем. Чем высокоуровневей концепция, тем менее ее видно из голого кода.
По крайней мере языку стоит стремится к поддержке выразительности. Насчет высокоуровневости не соглашусь, грамотное структкрирование не усложняет высокоуровневые сущности и функционал. Если интересно, приведите пример.
Хорошее соременное направление это потдержка IDE стандартных коментариев.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Ага, разговор о старом.
Пока исходный код бесструктурный, представлен плоским текстом, много сделать не получится. Исходный формат документации гораздо богаче простого текстового формата, т.е. на лицо фундаментальная причина невозможности интегрирования кода и доки по нему при существующем положении дел.
Вариант, когда код отдельно, а исходники доки отдельно не обладает достаточными ср-вами по обеспечению целостности, начиная от возможности банального расхождения независимых файлов, до неприятного факта отставания документации, создаваемой отдельно, при обычном рефакторинге.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Знаешь мы эту проблему довольно просто решили. Есть ребенок (почти бесплатный), который документирует все доксигеном (сам лазает по исходникам) и пишет описание, включая примеры использования и неявные предположения, в вордпрессовский блог. Почему блог а не вики? Хз, меня это не волновало, а инициатор такого процесса вики не любит почему-то.
Плюсов несколько. Во-первых, все обязаны писать так, чтобы ребенок понял. Если ребенок не понял, то ребенку следует объяснить.Во-вторых, появляется довольно полная документация, описанная хорошим языком. Ребенок также обязан писать чтобы все его понимали,без особого выпендрежа, но так, чтобы читать было не скучно. Минус только один -- через год ребенок начинает писать нормально, через два сваливает.
Здравствуйте, Anton Batenev, Вы писали:
AB>Но есть одна большая проблема — документацию надо писать и поддерживать. А против "некогда тратить время — надо код писать" не поможет никакая идеальная система
Всё прекрасно решается, если программист пишет код, а архитектор придумывает структуру и пишет комментарии. Архитектором может быть не человек, а подотдел.
Во всяком случае у нас такое работало превосходно, значительно лучше, чем если бы это делали программисты.
Здравствуйте, AndrewVK, Вы писали:
N>>И вообще, я бы предпочел, чтобы документация хранилась в отдельных XML файлах AVK>Почему XML?
Впрочем, это не важно, если мне не придется редактировать разметку в текстовом виде. Надо только, чтобы сравнения правок в системе контроля версий тоже выдавали результат в удобочитаемом виде.
N>>Ну букмарки, для навигации. Пометить место, потом туда вернуться. AVK>Если дока связана с кодом, и в коде букмарки есть, не хватит ли этого?
На больших страницах документации хотелось бы отмечать и позицию на странице. Потом, я могу захотеть вынести часть информации на отдельную страницу, на которую не будет прямых ссылок из кода, а будут ссылки, например, из описания каких-то классов.
AVK>>>В смысле прямо в редакторе кода? N>>Нет, не в редакторе кода, а сбоку. То есть в отдельной панели, а расположит ее пользователь, как захочет. AVK>Т.е. независимый WYSIWYG редактор?
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Внесу свои 5 копеек.
Несколько навеяно этим
.
В последнее время очень неплохо развились системы документирования классов, методов и полей, автоматическая генерация доков по описанию, отображение документации метода в IDE по наведению мыши и т.п. То есть в принципе можно достаточно сносно документировать API и удобно пользоваться(кстати, в этом смысле гораздо больше javadoc'ов и c# xml comment'ов мне нравится формат документирования в Fantom, так как отлично читается и без 'компиляции' в какой-нибудь rich text)Однако зачастую этого все же недостаточно — имеет смысл документировать и тело методов, а там, собственно, ничего не поменялось — // или /**/ в зубы и с plain text'ом на амбразуру. Возможно это оправдано, но иногда хочется и большего.
Еще несколько соображений:
— Где бы мы ни хранили документацию, в коде или рядом, она должна быть в виде 'исходников', типа wiki markup, чтобы можно было делать diff
— Опять же независимо от места хранения, IDE должна уметь показывать/скрывать документацию непосредственно в коде
— Во время компиляции должна проверяться целостность документации (отсутствие битых ссылок на код) и показываться в виде как минимум warning'ов
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Хочешь узнать это?
Поступи очень просто... Попробуй написать полноценную документацию к Решарперу или хотя бы к Янусу, тогда тебе сразу станет все очевидно.
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, Cyberax, Вы писали:
C>Если IDE умная, то она заменить комментарий @has_wiki на графическое изображение статьи (если оно небольшое). Возможно ещё имеет смысл сделать inline-редактирование.
Это попросту не нужно. В коде нужно отобразить только значок сигнализирующий, что есть расширенный комментарий. А сам комментарий показывать в виде хинта. Ну, а хинт уже может содержать кнопку "Редактировать...".
C>В общем, смысл в том, чтоб не требовалось отвлекаться на поиск документации по коду, чтобы документация его не захламляла, и чтобы код оставить чистым текстом.
+1
C>Ну или специальная тулза, не суть важно. Главное, чтобы можно было легко найти, где появились битые ссылки.
+1
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
1. Живой человек который изучит систему и буде отвечать на все вопросы
2. Документация которая построится сама по коду
Если серьёзно, был бы полезен критерий:
Источник данных для системы документирования не должен захламлять код, но должен оставлять в нём краткие комментарии со ссылкой на полные и перекрёстные.
Здравствуйте, minorlogic, Вы писали:
M>В полном идеале лучше ьез документирования, чтобы язык позволял максимально ясно передать то что хотел сделать програмист.
Это нереально, по крайней мере в ближайшем будущем. Чем высокоуровневей концепция, тем менее ее видно из голого кода.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
<q>Это значит, что всякие доксигены генерируют статическую документацию на основе комментариев</q>
Доксигены, к сожалению, генерируют документацию только для API. Они под это заточены. Многочисленные попытки приспособить доксиген и прочие natural docs для комментирования программ провалились.
<q>а нужна система, которая ничего бы не генерировала, а позволяла бы работать с документацией прямо из IDE. Т.е. можно было бы вывести документацию, просто ткнув мышью в непонятное место в программе;</q>
Серьезная проблема в связи кода и документации. Как показывает практика, малейший рефакторинг такую связь рвет, как оркский герой Тузик саблезадого тигра Грелку .
<q>Система управления документацией должна проверять целостность документации, автоматически находить незадокументированные части кода; части, для которых дата обновления документации меньше даты обновления кода; и т.д.</q>
Сможете реализовать — и до конца своих дней будете отдыхать на канарах . Пока ни у кого не получилось .
<q>Вариантов реализцаии может быть много, но в целом за основу должна быть взята идея "древовидного редактора"</q>
Это не реализация, это внешний вид самой простой части. Поверьте старику на слово, реализовать текстовый редактор любого форм-факторы — это очень простая задача. А вот как связать документацию с кодом чтобы всем было удобно и не рассыпалось через месяц — это основная проблема в данном вопросе. Я уже года четыре над этим работаю, результаты пока малоудовлетворительные . У остальных (silk edit сотоварищи) тоже ничего пока не получилось.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж.
Его не существует...
Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki. Куда можно было бы вставлять схемы, рисунки, screenshot'ы. И чтоб оно всё версировалось вместе с кодом с помощью одной SCM.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Обычно сейчас в наличии такие варианты:
* читать/редактировать комментарии в коде, причем всё форматирование будет в виде сырого языка разметки, объёмная документация вытесняет код с экрана, так как находится в том же окне
* смотреть комментарии к элементам кода в виде всяких всплывающих подсказок (по наведению мыши/клавиатурному шорткату), никакого редактирования, (иногда) примитивная навигация
* построить отдельный файл HTML-документации, и изучать его. Нет автоматической синхронизации с положением в коде, нельзя напрямую отредактировать, при обновлении комментариев в коде документация не обновляется автоматически
Что иногда хотелось бы (особенно при попытках изучить малознакомый код, написать какие-то заметки для себя и будущих поколений):
* Красиво отформатированная документация в отдельном окошке внутри IDE, которая умеет автоматически синхронизироваться с элементом кода, на котором находится курсор, в которой можно делать закладки, есть удобная навигация и которую можно редактировать прямо в режиме rich text.
Здравствуйте, Cyberax, Вы писали:
C>Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki. Куда можно было бы вставлять схемы, рисунки, screenshot'ы. И чтоб оно всё версировалось вместе с кодом с помощью одной SCM.
Но чтобы можно было посмотреть историю для кода и документации раздельно. То есть скрыть правки, где менялся только код или только документация.
Здравствуйте, nikov, Вы писали:
C>>Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki. Куда можно было бы вставлять схемы, рисунки, screenshot'ы. И чтоб оно всё версировалось вместе с кодом с помощью одной SCM. N>Но чтобы можно было посмотреть историю для кода и документации раздельно. То есть скрыть правки, где менялся только код или только документация.
По идее, это обычная функциональность нормальных VCS...
Здравствуйте, Cyberax, Вы писали:
AVK>>Хотелось бы обсудить сабж. C>Его не существует...
Я в курсе. Но мне было бы все таки интересно, в какую сторону имеет смысл копать.
C>Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki.
А наоборот?
C> Куда можно было бы вставлять схемы, рисунки, screenshot'ы.
Куда, в код? А редактировать как?
C> И чтоб оно всё версировалось вместе с кодом с помощью одной SCM.
Это понятно.
C>И чтоб компилятор проверял битые ссылки.
Именнно компилятор?
C>И ещё хочу пони.
Это шутка?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, nikov, Вы писали:
N>Что иногда хотелось бы (особенно при попытках изучить малознакомый код, написать какие-то заметки для себя и будущих поколений): N>* Красиво отформатированная документация в отдельном окошке внутри IDE, которая умеет автоматически синхронизироваться с элементом кода, на котором находится курсор
Именно в отдельном окошке? Или какие то еще приемлемые варианты есть?
N>, в которой можно делать закладки
В каком виде закладки и как их использовать?
N>, есть удобная навигация и которую можно редактировать прямо в режиме rich text.
В смысле прямо в редакторе кода? А как конкретно — всплывающие модальные окна, распахивающиеся блоки в редакторе, как то еще?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, NikeByNike, Вы писали:
NBN>1. Живой человек который изучит систему и буде отвечать на все вопросы
Живой человек, сам понимаешь, не всегда есть. А когда есть — может послать тебя далеко и надолго. В этом топике меня все таки технические аспекты интересуют.
NBN>2. Документация которая построится сама по коду
Это здорово. Вопрос в том, как. В примитивном виде это уже есть даже для С++, но что то оно не особо популярно постфактум.
NBN>Источник данных для системы документирования не должен захламлять код, но должен оставлять в нём краткие комментарии со ссылкой на полные и перекрёстные.
Раскрыть мысль не хочешь?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Здравствуйте, nikov, Вы писали:
n> Но чтобы можно было посмотреть историю для кода и документации раздельно. То есть скрыть правки, где менялся только код или только документация.
Doxygen позволяет разделять документацию и код по разным файлам, позволяет вставлять картинки, ссылки на внешние и внутренние источники, диаграммы, при сборке документации проверяется наличие файлов, и т.д.
Но есть одна большая проблема — документацию надо писать и поддерживать. А против "некогда тратить время — надо код писать" не поможет никакая идеальная система
Здравствуйте, AndrewVK, Вы писали:
AVK>Именно в отдельном окошке? Или какие то еще приемлемые варианты есть?
Да, я бы предпочел в отдельном окошке сбоку от кода. Это удобно, когда есть широкий экран (или два широких экрана )
И вообще, я бы предпочел, чтобы документация хранилась в отдельных XML файлах, и в коде были бы самое большее ссылки на них в комментариях. Чтобы система контроля версия могла легко различить, где правки в коде, а где в документации. И чтобы не заботиться сворачиванием/разворачиванием этой документации. Конечно, в некоторых местах кода могут встречаться короткие комментарии прямо внутри методов.
N>>, в которой можно делать закладки AVK>В каком виде закладки и как их использовать?
Ну букмарки, для навигации. Пометить место, потом туда вернуться.
N>>, есть удобная навигация и которую можно редактировать прямо в режиме rich text. AVK>В смысле прямо в редакторе кода?
Нет, не в редакторе кода, а сбоку. То есть в отдельной панели, а расположит ее пользователь, как захочет.
Здравствуйте, nikov, Вы писали:
N>И вообще, я бы предпочел, чтобы документация хранилась в отдельных XML файлах
Почему XML?
N>>>, в которой можно делать закладки AVK>>В каком виде закладки и как их использовать?
N>Ну букмарки, для навигации. Пометить место, потом туда вернуться.
Если дока связана с кодом, и в коде букмарки есть, не хватит ли этого?
AVK>>В смысле прямо в редакторе кода?
N>Нет, не в редакторе кода, а сбоку. То есть в отдельной панели, а расположит ее пользователь, как захочет.
Т.е. независимый WYSIWYG редактор?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
AVK> AB>Но есть одна большая проблема — документацию надо писать и поддерживать. AVK> Значит надо сделать так, чтобы на поддержание затрачивалось как можно меньше усилий, нет?
В пределе ноль? Но ты сам ниже ответил, что так не бывает.
Если же продолжить разговор про doxygen — им, как и любым инструментом, требуется овладеть. После этого основным усилием на поддержание документации будет усилие заставить себя ее поддерживать. Т.е. пока что до технических проблем самого инструментария мы и не дошли.
Здравствуйте, AndrewVK, Вы писали:
AVK>Это здорово. Вопрос в том, как. В примитивном виде это уже есть даже для С++, но что то оно не особо популярно постфактум.
Я идейки подкинул — для идеальной системы
NBN>>Источник данных для системы документирования не должен захламлять код, но должен оставлять в нём краткие комментарии со ссылкой на полные и перекрёстные.
AVK>Раскрыть мысль не хочешь?
Это для меня один из критериев. Условно говоря, такой вот код ИМХО не читабелен:
/**
* Sets bitmap with mask to the context pane and shows it in the status pane's
* context pane. Context pane object takes ownership of the bitmap.
* @param aBitmap new bitmap to the context pane.
* @param aMaskBitmap mask of the bitmap.
*/
IMPORT_C void SetPicture(const CFbsBitmap* aBitmap,
const CFbsBitmap* aMaskBitmap = NULL);
/**
* Sets bitmap to the context pane and shows it in the status pane's
* context pane. Context pane object takes ownership of the bitmap.
* @param aImage new bitmap and its mask.
*/
IMPORT_C void SetPicture(CEikImage* aImage);
/**
* Sets bitmap to the context pane from file and shows it in the status pane's
* context pane.
* @param aFileName name of the bitmap file.
* @param aMainId id of the bitmap in the bitmap file.
* @param aMaskId id of the bitmap's mask in the bitmap file.
*/
IMPORT_C void SetPictureFromFileL(const TDesC& aFileName,
TInt aMainId, TInt aMaskId = -1);
Здравствуйте, minorlogic, Вы писали:
M>По крайней мере языку стоит стремится к поддержке выразительности.
Это само собой. Но топик не об этом.
M> Насчет высокоуровневости не соглашусь, грамотное структкрирование не усложняет высокоуровневые сущности и функционал.
Хм, не уловил противоречия с тем, что сказал я.
M>Хорошее соременное направление это потдержка IDE стандартных коментариев.
Какая именно поддержка?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, NikeByNike, Вы писали:
AVK>>Это здорово. Вопрос в том, как. В примитивном виде это уже есть даже для С++, но что то оно не особо популярно постфактум. NBN>Я идейки подкинул — для идеальной системы
Так собственно, идей то и нет, ИМХО.
AVK>>Раскрыть мысль не хочешь? NBN>Это для меня один из критериев. Условно говоря, такой вот код ИМХО не читабелен:
NBN>А по моему ИМХО код таки должен быть читабельным.
Например?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Я думаю, что не надо отлынивать от написания документации. Программа и документация — взаимодополняющие тексты. Они написаны в разнух жанрах, и один не может заменить другого. У них даже структура [должна быть] разная. Документация должна описывать программу на концептуальном уровне, а не на уровне процедур и интерфейсов. Поэтому все эти автогенерилки документации из кода сосут, никакими автоматическими методами нельзя высосать из кода программы того, что в нем нет и не должно быть. Единственное назначение систем автоматического тугаментирования заключается в том, чтобы служить оправданием той лени, которая не дает нам писать нормальную документацию.
Здравствуйте, Pzz, Вы писали:
Pzz>Я думаю, что не надо отлынивать от написания документации. Программа и документация — взаимодополняющие тексты. Они написаны в разнух жанрах, и один не может заменить другого. У них даже структура [должна быть] разная. Документация должна описывать программу на концептуальном уровне, а не на уровне процедур и интерфейсов.
В принципе верно. Но есть и другая сторона медали — какие то перекрестные ссылки между документацией и кодом все таки быть должны. Особенно ссылки из документации на код.
Pzz> Поэтому все эти автогенерилки документации из кода сосут, никакими автоматическими методами нельзя высосать из кода программы того, что в нем нет и не должно быть.
Это как раз понятно. Вопрос в том, что не сосет.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
AVK>В принципе верно. Но есть и другая сторона медали — какие то перекрестные ссылки между документацией и кодом все таки быть должны. Особенно ссылки из документации на код.
Зачем? Достаточно структуру кода описать.
И кстати да, код надо проектировать так, чтобы его легко было описывать. Если ваш код невозможно описать словами, это плохой код, его надо переделать.
Pzz>> Поэтому все эти автогенерилки документации из кода сосут, никакими автоматическими методами нельзя высосать из кода программы того, что в нем нет и не должно быть.
AVK>Это как раз понятно. Вопрос в том, что не сосет.
Редактор текстов не сосет, при условии, если не лениться им пользоваться. Все остальное сосет.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Меня вполне устраивает текущее состояние в шарпе. То, что хранится в хмл прямо в коде или рядом. Но не устраивает поддержка IDE для редактирования xml-комментариев. [К сожелению, я куда-то потерял (может, пришлёт кто) Documentor, написанный когда-то небезызвестным Лютцем и сейчас уже убранный с его сайта. С ним было проще.]
Конкретно хотелось бы
При чтении видеть трансформированный xml в отдельном окошке. Отображение в нескольких режимах: по позиции каретки в редакторе или по позиции указателя мыши; отображение только непосредственно попавшего в "контекст" блока xml-документации или целиком "агрегированной" информации по файлу или типу.
В этом окошке может показываться или только трансформированный результат или же вдобавок исходный xml (разделены, например, сплиттером). Например, если коментарий забит прямо в коде, то показывается только превью, а если в коде стоит <include — то превью и исходный xml. В превью-панеле окошка есть специальная кнопка, переключающая режим ридонли и редактирования трансформированного текста (да-да, просили "любые мысли"…). Панель с исходным хмл — всегда редактируема.
При редактировании хмл как в коде, так и в панеле окошка должен быть (вдобавок к тому, что сейчас уже есть в студии) интеллисенс и автокомплит при редактировании значений атрибута ref. Конечно же, подсветка. Простой конструктор таблиц (по количеству строк и столбцов).
Возможно, в окошке будет полезно иметь и третью панель — с текстом (с подсветкой, ридонли — а может и нет) текущего контекста (метода\класса\всего файла). Тогда можно сделать следующий сценарий: в некотором месте (например, внутри объявления метода) жмёшь комбинацию клавиш и в редакторе появляется новая вкладка, в которой отдельно видно xml-коментарий, его трансформированное представление и комментируемый контекст.
В общем, требуется упрощение создания, редактирования и поддержания в актуальном состоянии документации. Как вот взяться за последнее ("поддержание") непонятно совсем
Help will always be given at Hogwarts to those who ask for it.
Здравствуйте, AndrewVK, Вы писали:
AVK>>>Это здорово. Вопрос в том, как. В примитивном виде это уже есть даже для С++, но что то оно не особо популярно постфактум. NBN>>Я идейки подкинул — для идеальной системы
AVK>Так собственно, идей то и нет, ИМХО.
Каков вопрос
По сути — система документирования должна быть сопряжена со средой разработки.
Исходники должны хранится не в простом текстовом виде.
Комментарии нужно уметь делать видимыми или нет, причём для разных видов комментариев по разному.
Например для сферического фрагмента:
/**
* Sets bitmap with mask to the context pane and shows it in the status pane's
* context pane. Context pane object takes ownership of the bitmap.
* @param aBitmap new bitmap to the context pane.
* @param aMaskBitmap mask of the bitmap.
*/
IMPORT_C void SetPicture(const CFbsBitmap* aBitmap,
const CFbsBitmap* aMaskBitmap = NULL);
/**
* [Sets "In My Humble Opinion" to the context pane] and shows it in the status pane's
* context pane. Context pane object takes ownership of the bitmap.
* @param aImage new bitmap and its mask.
*/
IMPORT_C void SetIMHO(IMHO * pIMHO );
Нужно чтобы показывалась полная форма, или редуцированная:
IMPORT_C void SetPicture(const CFbsBitmap* aBitmap,
const CFbsBitmap* aMaskBitmap = NULL);
// Sets "In My Humble Opinion" to the context pane
IMPORT_C void SetIMHO(IMHO * pIMHO );
И т.д.
Естественно при наведении курсора на функцию — должна показываться справка.
Сопряжённость системы документирования и редактирования должна корректно обрабатывать копипасты, удаления, переименования и прочие правки.
Сохраняя удалённые тексты для последующей автоподстановки.
Было бы полезно хранить в комментариях не только текст, но и картинки и более сложные объекты. Так чтобы их можно было быстро увидеть.
Было бы полезно видеть историю правок.
AVK>>>Раскрыть мысль не хочешь? NBN>>Это для меня один из критериев. Условно говоря, такой вот код ИМХО не читабелен:
NBN>>А по моему ИМХО код таки должен быть читабельным.
AVK>Например?
Для данного фрагмента, в данном контексте я вообще не вижу необходимости в комментариях. Т.е. они не нужны и должны хранится отдельно.
Однако по этим комментариям, я так полагаю, что доксидженом, строится документация. Т.е. по данному критерию — доксиджен становится не очень удобной системой для документирования (хотя там конечно можно хелп и отдельно писать, но, как минимум, для С++ это сложнее).
Затем что, в хорошей документации, обычно приведены, к примеру, публичные контракты, возможно в сокращенном виде. Или хотя бы ссылки на них.
Pzz> Достаточно структуру кода описать.
Что такое "структура кода" и как выглядит ее описание?
AVK>>Это как раз понятно. Вопрос в том, что не сосет. Pzz>Редактор текстов не сосет, при условии, если не лениться им пользоваться.
У него другие проблемы. Связь между текстовым редактором и кодом нулевая. Для полухудожественных overview это терпимо, для более детальной документации — неприемлемо.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
Pzz>>Зачем?
AVK>Затем что, в хорошей документации, обычно приведены, к примеру, публичные контракты, возможно в сокращенном виде. Или хотя бы ссылки на них.
Они у вас в файлах с расширением .h приведены. Зачем их еще раз дублировать в документации?
Pzz>> Достаточно структуру кода описать.
AVK>Что такое "структура кода" и как выглядит ее описание?
То, что этот модуль обслуживает красную кнопку, этот отвечает за пуск двигателей, этот за взрыв заряда на подлете а этот обеспечивает между ними коммуникацию.
AVK>У него другие проблемы. Связь между текстовым редактором и кодом нулевая. Для полухудожественных overview это терпимо, для более детальной документации — неприемлемо.
Она не нужна, более детальная документация. Зато всегда чертовски не хватает полухудожественного overview, в котором написано хотя бы, к чему все это и с какой стороны к этому подходить.
Здравствуйте, NikeByNike, Вы писали:
NBN>Исходники должны хранится не в простом текстовом виде.
А в каком?
NBN>Нужно чтобы показывалась полная форма, или редуцированная:
Прямо в редакторе кода, или как nikov считает, в отдельном окне?
NBN>Было бы полезно хранить в комментариях не только текст, но и картинки и более сложные объекты.
Прямо в комментариях? Или в отдельных файлах?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, _FRED_, Вы писали:
_FR>Меня вполне устраивает текущее состояние в шарпе. То, что хранится в хмл прямо в коде или рядом.
Ты считаешь, что документации, жестко увязанной с конкретными мемберами и типами достаточно?
_FR>При чтении видеть трансформированный xml в отдельном окошке.
А если прямо в редакторе?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, Pzz, Вы писали:
Pzz>Они у вас в файлах с расширением .h приведены. Зачем их еще раз дублировать в документации?
Наверное, потому что в .h много лишнего. Ну вот смотри — документация описывает некий сервис. Как мне в тексте ссылаться на элементы контракта сервиса? Просто текстовыми названиями? А потом, при чтении, нужно постоянно переключаться туда-сюда? А если потом, в результате рефакторинга, что то переименовалось? А если в доке опечатался в названии какого нибудь метода?
AVK>>Что такое "структура кода" и как выглядит ее описание?
Pzz>То, что этот модуль обслуживает красную кнопку, этот отвечает за пуск двигателей, этот за взрыв заряда на подлете а этот обеспечивает между ними коммуникацию.
Хм, не понял.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
NBN>>Исходники должны хранится не в простом текстовом виде.
AVK>А в каком?
Не суть.
NBN>>Нужно чтобы показывалась полная форма, или редуцированная:
AVK>Прямо в редакторе кода, или как nikov считает, в отдельном окне?
Можно и прямо в редакторе (если в лоб — то так вроде удобнее) и отдельно.
NBN>>Было бы полезно хранить в комментариях не только текст, но и картинки и более сложные объекты.
AVK>Прямо в комментариях? Или в отдельных файлах?
Прямо в комментариях. Естественно с возможностью отредактировать или спрятать при необходимости.
Здравствуйте, NikeByNike, Вы писали:
NBN>>>Исходники должны хранится не в простом текстовом виде. AVK>>А в каком? NBN>Не суть.
Тогда не понимаю. Если ты сделал акцент на нетекстовом виде — наверное были тому какие то причины? Какие?
AVK>>Прямо в комментариях? Или в отдельных файлах? NBN>Прямо в комментариях. Естественно с возможностью отредактировать или спрятать при необходимости.
Картинки могут легко занимать десятки килобайт. А код — десятки байт. Считаешь это нормально? Ну хотя бы в разрезе VCS? Или нужен специальный VCS, который тоже будет это все скрывать?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
NBN>>>>Исходники должны хранится не в простом текстовом виде. AVK>>>А в каком? NBN>>Не суть.
AVK>Тогда не понимаю. Если ты сделал акцент на нетекстовом виде — наверное были тому какие то причины? Какие?
Выделил. Если делать документирование более полным — понадобятся картинки, а хранить картинки в символьном виде не очень удобно.
Кроме того — символы форматирования конечно решение, но не очень удобное, а следовательно не для идеальной системы. Условно говоря — в ворде мы пользуемся специальными инструментами, а не пишем всё с помощью тегов, как в HTML.
AVK>>>Прямо в комментариях? Или в отдельных файлах? NBN>>Прямо в комментариях. Естественно с возможностью отредактировать или спрятать при необходимости.
AVK>Картинки могут легко занимать десятки килобайт. А код — десятки байт. Считаешь это нормально?
Ну какой смысл в наши времена считать байты? Твоя же задача сделать удобную работу для программиста-разработчика, документатора и того кому всё это нужно. А всем троим по сути от одного кода нужно разное. Ресурсы при этом ИМХО низкоприоритетны, так как задача — обеспечить высокую производительность команде.
AVK>Ну хотя бы в разрезе VCS? Или нужен специальный VCS, который тоже будет это все скрывать?
А почему бы и нет? Хотя по сути можно обойтись плагинами к уже существующим.
Здравствуйте, AndrewVK, Вы писали:
_FR>>Меня вполне устраивает текущее состояние в шарпе. То, что хранится в хмл прямо в коде или рядом.
AVK>Ты считаешь, что документации, жестко увязанной с конкретными мемберами и типами достаточно?
Нет, но такая документация получается не связанной непосредственно с кодом. Документация, конечно же, должна состоять не только из описания мемберов, но и из общего описания архитектуры, примеров, гайдлайнов и т.п. Это всё (говоря просто) можно сделать и в ворде (или в xml-редакторе студии), запущенном рядом со студией. По крайней мере, написание такой вот документации (то есть отвязанной от кода) мне не кажется такой большой проблемой, как написание документации, привязанной к коду. Последнюю надо чаще менять и неудобство самого процесса редактирования очень останавливает от написания документации совсем
_FR>>При чтении видеть трансформированный xml в отдельном окошке. AVK>А если прямо в редакторе?
Если придумать, как органично прямо в редакторе показать и оригинальный и трансформированный — это, конечно, совсем круто будет. Но нужно иметь возможность менять и сам xml и трансформированный результат и даже тогда, когда xml во внешнем файле (то есть пользователь должен как-то знать — то есть ему надо показать, что он редактирует не inplace-документацию).
Help will always be given at Hogwarts to those who ask for it.
Здравствуйте, NikeByNike, Вы писали:
NBN>Выделил. Если делать документирование более полным — понадобятся картинки, а хранить картинки в символьном виде не очень удобно.
Т.е. имелся ввиду rich text?
AVK>>Картинки могут легко занимать десятки килобайт. А код — десятки байт. Считаешь это нормально? NBN>Ну какой смысл в наши времена считать байты?
Дело не в байтах, дело в их соотношении. Если исходник будет засран непонятным мусором, вряд ли это будет удобно, даже при наличии специальной IDE.
AVK>>Ну хотя бы в разрезе VCS? Или нужен специальный VCS, который тоже будет это все скрывать? NBN>А почему бы и нет?
Ну, наверное потому что переписывание стандартных тулов, работающих с текстом — не самая лучшая идея?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
_FR>> Это всё (говоря просто) можно сделать и в ворде (или в xml-редакторе студии), запущенном рядом со студией.
AVK>Можно. Считаешь это идеалом?
Считаю это просто отдельной большой темой, менее актуальной лично для меня Если это так же интересует, то и про это напишу.
Help will always be given at Hogwarts to those who ask for it.
Здравствуйте, _FRED_, Вы писали:
_FR>Считаю это просто отдельной большой темой, менее актуальной лично для меня Если это так же интересует, то и про это напишу.
Напиши.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
NBN>>Выделил. Если делать документирование более полным — понадобятся картинки, а хранить картинки в символьном виде не очень удобно.
AVK>Т.е. имелся ввиду rich text?
Что-то на подобии. Оно должно комбинироваться с обычным кодом.
AVK>>>Картинки могут легко занимать десятки килобайт. А код — десятки байт. Считаешь это нормально? NBN>>Ну какой смысл в наши времена считать байты?
AVK>Дело не в байтах, дело в их соотношении. Если исходник будет засран непонятным мусором, вряд ли это будет удобно, даже при наличии специальной IDE.
В целом, это проблема техническая. Не вижу особых проблем с её решением.
Тяжёлую информацию можно смещать в конец файла, оставляя в начале исходник и разметку. Размер получается не таким уж большим. Для того же симбиана — с презентациями, картинками и прочим — ~30Кб на файл.
Т.е. проектировать сейчас не буду, по моему это не существенная проблема по сравнению с проектированием хорошей системы документирования.
AVK>>>Ну хотя бы в разрезе VCS? Или нужен специальный VCS, который тоже будет это все скрывать? NBN>>А почему бы и нет?
AVK>Ну, наверное потому что переписывание стандартных тулов, работающих с текстом — не самая лучшая идея?
Ну ты же написал про идеальную систему, там не было написано: "идеальная минималистичная система документирования кода".
Так что я просто предлагаю руководствуясь сабжем, а не ресурсными ограничениями.
Здравствуйте, NikeByNike, Вы писали:
AVK>>Дело не в байтах, дело в их соотношении. Если исходник будет засран непонятным мусором, вряд ли это будет удобно, даже при наличии специальной IDE. NBN>В целом, это проблема техническая. Не вижу особых проблем с её решением.
Хотелось бы понять — нужно ли ее решать. И если нужно, то зачем. Тут вот рядом говорят, что наоборот, документация должна быть в отдельном файле, потому что так удобнее.
NBN>Так что я просто предлагаю руководствуясь сабжем, а не ресурсными ограничениями.
Тогда поясни, почему нужно хранить вообще все внутри исходника.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
NBN>>В целом, это проблема техническая. Не вижу особых проблем с её решением.
AVK>Хотелось бы понять — нужно ли ее решать. И если нужно, то зачем. Тут вот рядом говорят, что наоборот, документация должна быть в отдельном файле, потому что так удобнее.
Оно ИМХО зависит от бюджета. Если решать минималистично, то допустим для С++ — ещё один файл с некоторой автоматизацией был бы удобнее.
Если комплексно — то лучше наверное один, меньше проблем с менеджементом файлов.
Хотя — ничего не мешает сделать всё опционально.
NBN>>Так что я просто предлагаю руководствуясь сабжем, а не ресурсными ограничениями.
AVK>Тогда поясни, почему нужно хранить вообще все внутри исходника.
Предлагая это я представил себе пакет офисных файлов посвящённых какому-либо проекту. Было бы неудобно манипулировать ими, если бы, скажем картинки лежали отдельно.
Здравствуйте, NikeByNike, Вы писали:
AVK>>Хотелось бы понять — нужно ли ее решать. И если нужно, то зачем. Тут вот рядом говорят, что наоборот, документация должна быть в отдельном файле, потому что так удобнее. NBN>Оно ИМХО зависит от бюджета.
Бюджета чего?
NBN>Если комплексно — то лучше наверное один, меньше проблем с менеджементом файлов.
Каких проблем?
AVK>>Тогда поясни, почему нужно хранить вообще все внутри исходника.
NBN>Предлагая это я представил себе пакет офисных файлов посвящённых какому-либо проекту. Было бы неудобно манипулировать ими, если бы, скажем картинки лежали отдельно.
В каком смысле манипулировать? Если речь идет о разработке, то очень даже удобно. Если об использовании каким то сторонним пользователем, без доступа к VCS — никто ж ведь не мешает сконвертировать в тот самый офисный файл без внешних ссылок.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
AVK>Наверное, потому что в .h много лишнего. Ну вот смотри — документация описывает некий сервис. Как мне в тексте ссылаться на элементы контракта сервиса? Просто текстовыми названиями? А потом, при чтении, нужно постоянно переключаться туда-сюда? А если потом, в результате рефакторинга, что то переименовалось? А если в доке опечатался в названии какого нибудь метода?
Че такое "элементы контракта сервиса"? Если сервис реализует некий протокол для общения с внешним миром, протокол, безусловно, должен быть документирован.
Pzz>>То, что этот модуль обслуживает красную кнопку, этот отвечает за пуск двигателей, этот за взрыв заряда на подлете а этот обеспечивает между ними коммуникацию.
AVK>Хм, не понял.
Ну вот представьте себе, попадет мне в руки ваша программа, с целью чего-нибудь добавить или починить. Как я узнаю, куда лезть. Конструкция программы, ее основные части, взаимодействие между ними должны быть описаны. Не на уровне каждого вспомогательного класса из трех строк, а на уровне, когда детали не важны.
Но разумеется, если у вас в программе нет четкой структуры, и любая единица функциональности размазана тонким слоем по всей программе, вам не удастся ее таким образом документировать. Это повод задуматься о существенных архитектурных проблемах.
Здравствуйте, AndrewVK, Вы писали:
AVK>>>Хотелось бы понять — нужно ли ее решать. И если нужно, то зачем. Тут вот рядом говорят, что наоборот, документация должна быть в отдельном файле, потому что так удобнее. NBN>>Оно ИМХО зависит от бюджета.
AVK>Бюджета чего?
Разработки идеальной системы документирования кода.
NBN>>Если комплексно — то лучше наверное один, меньше проблем с менеджементом файлов.
AVK>Каких проблем?
К примеру — скопировал файл из одного проекта в другой — и тем самым автоматически перенёс сопутствующую документацию.
AVK>>>Тогда поясни, почему нужно хранить вообще все внутри исходника.
NBN>>Предлагая это я представил себе пакет офисных файлов посвящённых какому-либо проекту. Было бы неудобно манипулировать ими, если бы, скажем картинки лежали отдельно.
AVK>В каком смысле манипулировать? Если речь идет о разработке, то очень даже удобно.
Это удобно для разработки проекта как такового. А создание документации — это не совсем та разработка, это скорее писательская деятельность. А следовательно см. MS Word.
AVK>Если об использовании каким то сторонним пользователем, без доступа к VCS
Кстати, с ходу кажется, что для твоего-же VCS один файл будет удобнее. Можно смотреть хистори более комплексно.
AVK>никто ж ведь не мешает сконвертировать в тот самый офисный файл без внешних ссылок.
Просто не вижу смысла для полноценной системы хранить всё по отдельности. Хотя при использовании полноценных средств — оно и не исключается. Например если к комментариям захочется приложить видео.
Здравствуйте, AndrewVK, Вы писали:
C>>Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki.
AVK>А наоборот?
Основная проблема — код не уникален. Без наличия лишних идентификаторов в коде ты не сможешь точно его идентифицировать. При изменении кода будет масса проблем. Ну, а разные там гуиды захлаляют код и делают код.
Если ты о решарпере, то имело бы смысл воспользоваться идей добавления гуидов ко всем значимым элементам кода и сокрытие их в IDE (отображение вмесо них хинтов и т.п.).
C>> Куда можно было бы вставлять схемы, рисунки, screenshot'ы.
AVK>Куда, в код? А редактировать как?
Если речь об IDE, то проблем нет. Навел мышку на метод, вылез хинт. На хинте может быть кнпка "редактировать". Нажал ее, открылся редактор. Поредактировать, записался... хинт обновился.
Но это означает, что IDE полность берет на себя отображение и управление кодом. Даже контроль весрий и то без IDE будет невозможен. Для Джетбрэйнса может это и хорошо. Для пользователей однозначно плохо.
C>>И чтоб компилятор проверял битые ссылки.
AVK>Именнно компилятор?
Есть мнение, что не должно быть деления на движок IDE и компилятор. Но опять же для вас это пока что будет проблематично.
C>>И ещё хочу пони.
AVK>Это шутка?
Нет, конечно. Подари ему...
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, AndrewVK, Вы писали:
AVK>В смысле прямо в редакторе кода? А как конкретно — всплывающие модальные окна, распахивающиеся блоки в редакторе, как то еще?
Вот только не модальные! Лучше всего отдельная закладка в IDE.
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, AndrewVK, Вы писали:
AVK>Тогда поясни, почему нужно хранить вообще все внутри исходника.
Скорее — исходник внутри какого-нить формата. Для примера: вот у вас есть некий шаблон для статей rsdn, и некий тул, под этот шаблон заточенный. Мог бы быть некий стиль "code" откуда можно было брать текст и вскармливать компилятору по прямому назначению, или же тулу для генерации хелпа по исходникам (для C# — тоже компилятор), а полученный автогенеренный хелп интегрировать обратно. В принципе, на коленке за несколько часов делается.
На самом деле использовать Ворд, конечно, не предлагаю. Просто это пример возможных сценариев, если будет использован некий структурный формат хранения исходников + WISYWING-редаутор для комплексного контента уровня современного Ворда.
Здравствуйте, AndrewVK, Вы писали:
AVK>Здравствуйте, minorlogic, Вы писали:
M>> Насчет высокоуровневости не соглашусь, грамотное структкрирование не усложняет высокоуровневые сущности и функционал.
AVK>Хм, не уловил противоречия с тем, что сказал я.
"Чем высокоуровневей концепция, тем менее ее видно из голого кода." с этим.
Это не всегда так, а задача програмиста делать чтобы это всегда было не так.
M>>Хорошее соременное направление это потдержка IDE стандартных коментариев.
AVK>Какая именно поддержка?
Подсветка коментариев для переменных, функций, классов и т.п. (хинты)
Здравствуйте, VladD2, Вы писали:
C>>Если IDE умная, то она заменить комментарий @has_wiki на графическое изображение статьи (если оно небольшое). Возможно ещё имеет смысл сделать inline-редактирование. VD>Это попросту не нужно. В коде нужно отобразить только значок сигнализирующий, что есть расширенный комментарий. А сам комментарий показывать в виде хинта. Ну, а хинт уже может содержать кнопку "Редактировать...".
Я бы не отказался. Банально приятно было бы видеть комментарий с rich-text'ом перед функцией вместо обычного JavaDoc'а или XML-комментария в C#.
Естественно, всё это должно настраиваться под личные предпочтения.
Здравствуйте, 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>>
Здравствуйте, 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>>
Здравствуйте, 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++.
Но от лошадки всё равно бы не отказался.
