Здравствуйте, AndrewVK, Вы писали:

N>>И вообще, я бы предпочел, чтобы документация хранилась в отдельных XML файлах
AVK>Почему XML?

Впрочем, это не важно, если мне не придется редактировать разметку в текстовом виде. Надо только, чтобы сравнения правок в системе контроля версий тоже выдавали результат в удобочитаемом виде.

N>>Ну букмарки, для навигации. Пометить место, потом туда вернуться.
AVK>Если дока связана с кодом, и в коде букмарки есть, не хватит ли этого?

На больших страницах документации хотелось бы отмечать и позицию на странице. Потом, я могу захотеть вынести часть информации на отдельную страницу, на которую не будет прямых ссылок из кода, а будут ссылки, например, из описания каких-то классов.

AVK>>>В смысле прямо в редакторе кода?
N>>Нет, не в редакторе кода, а сбоку. То есть в отдельной панели, а расположит ее пользователь, как захочет.
AVK>Т.е. независимый WYSIWYG редактор?

Да.

Здравствуйте, AndrewVK, Вы писали:

AVK>Здравствуйте, minorlogic, Вы писали:

M>>В полном идеале лучше ьез документирования, чтобы язык позволял максимально ясно передать то что хотел сделать програмист.

AVK>Это нереально, по крайней мере в ближайшем будущем. Чем высокоуровневей концепция, тем менее ее видно из голого кода.

По крайней мере языку стоит стремится к поддержке выразительности. Насчет высокоуровневости не соглашусь, грамотное структкрирование не усложняет высокоуровневые сущности и функционал. Если интересно, приведите пример.


Хорошее соременное направление это потдержка IDE стандартных коментариев.

Здравствуйте, 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 стандартных коментариев.

Какая именно поддержка?

Здравствуйте, Anton Batenev, Вы писали:

AB>Но есть одна большая проблема — документацию надо писать и поддерживать. А против "некогда тратить время — надо код писать" не поможет никакая идеальная система
Всё прекрасно решается, если программист пишет код, а архитектор придумывает структуру и пишет комментарии. Архитектором может быть не человек, а подотдел.
Во всяком случае у нас такое работало превосходно, значительно лучше, чем если бы это делали программисты.

Здравствуйте, NikeByNike, Вы писали:

AVK>>Это здорово. Вопрос в том, как. В примитивном виде это уже есть даже для С++, но что то оно не особо популярно постфактум.
NBN>Я идейки подкинул — для идеальной системы

Так собственно, идей то и нет, ИМХО.

AVK>>Раскрыть мысль не хочешь?
NBN>Это для меня один из критериев. Условно говоря, такой вот код ИМХО не читабелен:

NBN>А по моему ИМХО код таки должен быть читабельным.

Например?

Здравствуйте, AndrewVK, Вы писали:

AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.

Я думаю, что не надо отлынивать от написания документации. Программа и документация — взаимодополняющие тексты. Они написаны в разнух жанрах, и один не может заменить другого. У них даже структура [должна быть] разная. Документация должна описывать программу на концептуальном уровне, а не на уровне процедур и интерфейсов. Поэтому все эти автогенерилки документации из кода сосут, никакими автоматическими методами нельзя высосать из кода программы того, что в нем нет и не должно быть. Единственное назначение систем автоматического тугаментирования заключается в том, чтобы служить оправданием той лени, которая не дает нам писать нормальную документацию.

Здравствуйте, Pzz, Вы писали:

Pzz>Я думаю, что не надо отлынивать от написания документации. Программа и документация — взаимодополняющие тексты. Они написаны в разнух жанрах, и один не может заменить другого. У них даже структура [должна быть] разная. Документация должна описывать программу на концептуальном уровне, а не на уровне процедур и интерфейсов.

В принципе верно. Но есть и другая сторона медали — какие то перекрестные ссылки между документацией и кодом все таки быть должны. Особенно ссылки из документации на код.

Pzz> Поэтому все эти автогенерилки документации из кода сосут, никакими автоматическими методами нельзя высосать из кода программы того, что в нем нет и не должно быть.

Это как раз понятно. Вопрос в том, что не сосет.

Здравствуйте, AndrewVK, Вы писали:

AVK>В принципе верно. Но есть и другая сторона медали — какие то перекрестные ссылки между документацией и кодом все таки быть должны. Особенно ссылки из документации на код.

Зачем? Достаточно структуру кода описать.

И кстати да, код надо проектировать так, чтобы его легко было описывать. Если ваш код невозможно описать словами, это плохой код, его надо переделать.

Pzz>> Поэтому все эти автогенерилки документации из кода сосут, никакими автоматическими методами нельзя высосать из кода программы того, что в нем нет и не должно быть.

AVK>Это как раз понятно. Вопрос в том, что не сосет.

Редактор текстов не сосет, при условии, если не лениться им пользоваться. Все остальное сосет.

Здравствуйте, AndrewVK, Вы писали:

AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.

Меня вполне устраивает текущее состояние в шарпе. То, что хранится в хмл прямо в коде или рядом. Но не устраивает поддержка IDE для редактирования xml-комментариев. [К сожелению, я куда-то потерял (может, пришлёт кто) Documentor, написанный когда-то небезызвестным Лютцем и сейчас уже убранный с его сайта. С ним было проще.]

Конкретно хотелось бы
При чтении видеть трансформированный xml в отдельном окошке. Отображение в нескольких режимах: по позиции каретки в редакторе или по позиции указателя мыши; отображение только непосредственно попавшего в "контекст" блока xml-документации или целиком "агрегированной" информации по файлу или типу.

В этом окошке может показываться или только трансформированный результат или же вдобавок исходный xml (разделены, например, сплиттером). Например, если коментарий забит прямо в коде, то показывается только превью, а если в коде стоит <include — то превью и исходный xml. В превью-панеле окошка есть специальная кнопка, переключающая режим ридонли и редактирования трансформированного текста (да-да, просили "любые мысли"…). Панель с исходным хмл — всегда редактируема.

При редактировании хмл как в коде, так и в панеле окошка должен быть (вдобавок к тому, что сейчас уже есть в студии) интеллисенс и автокомплит при редактировании значений атрибута ref. Конечно же, подсветка. Простой конструктор таблиц (по количеству строк и столбцов).

Возможно, в окошке будет полезно иметь и третью панель — с текстом (с подсветкой, ридонли — а может и нет) текущего контекста (метода\класса\всего файла). Тогда можно сделать следующий сценарий: в некотором месте (например, внутри объявления метода) жмёшь комбинацию клавиш и в редакторе появляется новая вкладка, в которой отдельно видно xml-коментарий, его трансформированное представление и комментируемый контекст.

В общем, требуется упрощение создания, редактирования и поддержания в актуальном состоянии документации. Как вот взяться за последнее ("поддержание") непонятно совсем

Здравствуйте, 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, Вы писали:

Pzz>Зачем?

Затем что, в хорошей документации, обычно приведены, к примеру, публичные контракты, возможно в сокращенном виде. Или хотя бы ссылки на них.

Pzz> Достаточно структуру кода описать.

Что такое "структура кода" и как выглядит ее описание?

AVK>>Это как раз понятно. Вопрос в том, что не сосет.
Pzz>Редактор текстов не сосет, при условии, если не лениться им пользоваться.

У него другие проблемы. Связь между текстовым редактором и кодом нулевая. Для полухудожественных overview это терпимо, для более детальной документации — неприемлемо.

Здравствуйте, AndrewVK, Вы писали:

Pzz>>Зачем?

AVK>Затем что, в хорошей документации, обычно приведены, к примеру, публичные контракты, возможно в сокращенном виде. Или хотя бы ссылки на них.

Они у вас в файлах с расширением .h приведены. Зачем их еще раз дублировать в документации?

Pzz>> Достаточно структуру кода описать.

AVK>Что такое "структура кода" и как выглядит ее описание?

То, что этот модуль обслуживает красную кнопку, этот отвечает за пуск двигателей, этот за взрыв заряда на подлете а этот обеспечивает между ними коммуникацию.

AVK>У него другие проблемы. Связь между текстовым редактором и кодом нулевая. Для полухудожественных overview это терпимо, для более детальной документации — неприемлемо.

Она не нужна, более детальная документация. Зато всегда чертовски не хватает полухудожественного overview, в котором написано хотя бы, к чему все это и с какой стороны к этому подходить.

Здравствуйте, NikeByNike, Вы писали:

NBN>Исходники должны хранится не в простом текстовом виде.

А в каком?

NBN>Нужно чтобы показывалась полная форма, или редуцированная:

Прямо в редакторе кода, или как nikov считает, в отдельном окне?

NBN>Было бы полезно хранить в комментариях не только текст, но и картинки и более сложные объекты.

Прямо в комментариях? Или в отдельных файлах?

Здравствуйте, _FRED_, Вы писали:

_FR>Меня вполне устраивает текущее состояние в шарпе. То, что хранится в хмл прямо в коде или рядом.

Ты считаешь, что документации, жестко увязанной с конкретными мемберами и типами достаточно?

_FR>При чтении видеть трансформированный xml в отдельном окошке.

А если прямо в редакторе?

Здравствуйте, Pzz, Вы писали:

Pzz>Они у вас в файлах с расширением .h приведены. Зачем их еще раз дублировать в документации?

Наверное, потому что в .h много лишнего. Ну вот смотри — документация описывает некий сервис. Как мне в тексте ссылаться на элементы контракта сервиса? Просто текстовыми названиями? А потом, при чтении, нужно постоянно переключаться туда-сюда? А если потом, в результате рефакторинга, что то переименовалось? А если в доке опечатался в названии какого нибудь метода?

AVK>>Что такое "структура кода" и как выглядит ее описание?

Pzz>То, что этот модуль обслуживает красную кнопку, этот отвечает за пуск двигателей, этот за взрыв заряда на подлете а этот обеспечивает между ними коммуникацию.

Хм, не понял.

Здравствуйте, AndrewVK, Вы писали:

NBN>>Исходники должны хранится не в простом текстовом виде.

AVK>А в каком?

Не суть.

NBN>>Нужно чтобы показывалась полная форма, или редуцированная:

AVK>Прямо в редакторе кода, или как nikov считает, в отдельном окне?

Можно и прямо в редакторе (если в лоб — то так вроде удобнее) и отдельно.

NBN>>Было бы полезно хранить в комментариях не только текст, но и картинки и более сложные объекты.

AVK>Прямо в комментариях? Или в отдельных файлах?
Прямо в комментариях. Естественно с возможностью отредактировать или спрятать при необходимости.

Здравствуйте, NikeByNike, Вы писали:

NBN>>>Исходники должны хранится не в простом текстовом виде.
AVK>>А в каком?
NBN>Не суть.

Тогда не понимаю. Если ты сделал акцент на нетекстовом виде — наверное были тому какие то причины? Какие?

AVK>>Прямо в комментариях? Или в отдельных файлах?
NBN>Прямо в комментариях. Естественно с возможностью отредактировать или спрятать при необходимости.

Картинки могут легко занимать десятки килобайт. А код — десятки байт. Считаешь это нормально? Ну хотя бы в разрезе VCS? Или нужен специальный VCS, который тоже будет это все скрывать?

Здравствуйте, AndrewVK, Вы писали:

NBN>>>>Исходники должны хранится не в простом текстовом виде.
AVK>>>А в каком?
NBN>>Не суть.

AVK>Тогда не понимаю. Если ты сделал акцент на нетекстовом виде — наверное были тому какие то причины? Какие?
Выделил. Если делать документирование более полным — понадобятся картинки, а хранить картинки в символьном виде не очень удобно.
Кроме того — символы форматирования конечно решение, но не очень удобное, а следовательно не для идеальной системы. Условно говоря — в ворде мы пользуемся специальными инструментами, а не пишем всё с помощью тегов, как в HTML.

AVK>>>Прямо в комментариях? Или в отдельных файлах?
NBN>>Прямо в комментариях. Естественно с возможностью отредактировать или спрятать при необходимости.

AVK>Картинки могут легко занимать десятки килобайт. А код — десятки байт. Считаешь это нормально?
Ну какой смысл в наши времена считать байты? Твоя же задача сделать удобную работу для программиста-разработчика, документатора и того кому всё это нужно. А всем троим по сути от одного кода нужно разное. Ресурсы при этом ИМХО низкоприоритетны, так как задача — обеспечить высокую производительность команде.

AVK>Ну хотя бы в разрезе VCS? Или нужен специальный VCS, который тоже будет это все скрывать?
А почему бы и нет? Хотя по сути можно обойтись плагинами к уже существующим.

Здравствуйте, AndrewVK, Вы писали:

_FR>>Меня вполне устраивает текущее состояние в шарпе. То, что хранится в хмл прямо в коде или рядом.

AVK>Ты считаешь, что документации, жестко увязанной с конкретными мемберами и типами достаточно?

Нет, но такая документация получается не связанной непосредственно с кодом. Документация, конечно же, должна состоять не только из описания мемберов, но и из общего описания архитектуры, примеров, гайдлайнов и т.п. Это всё (говоря просто) можно сделать и в ворде (или в xml-редакторе студии), запущенном рядом со студией. По крайней мере, написание такой вот документации (то есть отвязанной от кода) мне не кажется такой большой проблемой, как написание документации, привязанной к коду. Последнюю надо чаще менять и неудобство самого процесса редактирования очень останавливает от написания документации совсем

_FR>>При чтении видеть трансформированный xml в отдельном окошке.
AVK>А если прямо в редакторе?

Если придумать, как органично прямо в редакторе показать и оригинальный и трансформированный — это, конечно, совсем круто будет. Но нужно иметь возможность менять и сам xml и трансформированный результат и даже тогда, когда xml во внешнем файле (то есть пользователь должен как-то знать — то есть ему надо показать, что он редактирует не inplace-документацию).