Здравствуйте, 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>А наоборот?
Тоже надо, но смысла меньше. Скорее подойдёт простой обратный индекс. Типа "кто ссылается на меня из кода".
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>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Ага, разговор о старом.
Пока исходный код бесструктурный, представлен плоским текстом, много сделать не получится. Исходный формат документации гораздо богаче простого текстового формата, т.е. на лицо фундаментальная причина невозможности интегрирования кода и доки по нему при существующем положении дел.
Вариант, когда код отдельно, а исходники доки отдельно не обладает достаточными ср-вами по обеспечению целостности, начиная от возможности банального расхождения независимых файлов, до неприятного факта отставания документации, создаваемой отдельно, при обычном рефакторинге.
Здравствуйте, AndrewVK, Вы писали:
C>>Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki.
AVK>А наоборот?
Основная проблема — код не уникален. Без наличия лишних идентификаторов в коде ты не сможешь точно его идентифицировать. При изменении кода будет масса проблем. Ну, а разные там гуиды захлаляют код и делают код.
Если ты о решарпере, то имело бы смысл воспользоваться идей добавления гуидов ко всем значимым элементам кода и сокрытие их в IDE (отображение вмесо них хинтов и т.п.).
C>> Куда можно было бы вставлять схемы, рисунки, screenshot'ы.
AVK>Куда, в код? А редактировать как?
Если речь об IDE, то проблем нет. Навел мышку на метод, вылез хинт. На хинте может быть кнпка "редактировать". Нажал ее, открылся редактор. Поредактировать, записался... хинт обновился.
Но это означает, что IDE полность берет на себя отображение и управление кодом. Даже контроль весрий и то без IDE будет невозможен. Для Джетбрэйнса может это и хорошо. Для пользователей однозначно плохо.
C>>И чтоб компилятор проверял битые ссылки.
AVK>Именнно компилятор?
Есть мнение, что не должно быть деления на движок IDE и компилятор. Но опять же для вас это пока что будет проблематично.
C>>И ещё хочу пони.
AVK>Это шутка?
Нет, конечно. Подари ему...
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, Cyberax, Вы писали:
C>Если IDE умная, то она заменить комментарий @has_wiki на графическое изображение статьи (если оно небольшое). Возможно ещё имеет смысл сделать inline-редактирование.
Это попросту не нужно. В коде нужно отобразить только значок сигнализирующий, что есть расширенный комментарий. А сам комментарий показывать в виде хинта. Ну, а хинт уже может содержать кнопку "Редактировать...".
C>В общем, смысл в том, чтоб не требовалось отвлекаться на поиск документации по коду, чтобы документация его не захламляла, и чтобы код оставить чистым текстом.
+1
C>Ну или специальная тулза, не суть важно. Главное, чтобы можно было легко найти, где появились битые ссылки.
+1
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, AndrewVK, Вы писали:
AVK>В смысле прямо в редакторе кода? А как конкретно — всплывающие модальные окна, распахивающиеся блоки в редакторе, как то еще?
Вот только не модальные! Лучше всего отдельная закладка в IDE.
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Хочешь узнать это?
Поступи очень просто... Попробуй написать полноценную документацию к Решарперу или хотя бы к Янусу, тогда тебе сразу станет все очевидно.
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, 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#.
Естественно, всё это должно настраиваться под личные предпочтения.
Если это так же интересует, то и про это напишу.
Но от лошадки всё равно бы не отказался.
