Проголосовал за последний вариант, желаю объяснить позицию.
Лучшая документация — это сам код. Комментарии для документации читаются не только в документации, но и в коде.
Т.к. документация пишется в комментарии, "DSL" для неё имеет только одно техническое требование: чтобы оставался комментарием в соответствующем языке. Чем проще и читабельнее, тем лучше.
Вот пример правильного комментария для документации. http://java.sun.com/j2se/javadoc/writingdoccomments/#format
Можно ещё упростить: вместо @param p1 использовать @p1 и писать менее развёрнуто.
XML же просто замусоривает код своим синтаксическим оверхедом, он не самый лучший язык разметки для данного случая. Convert absloutely everything to XML ?
Во блин А я вначале как раз хотел тему создать, потом решил просто голосовалку.
Сейчас я пишу везде, но заметил, что немногие так делают.
AG>Проголосовал за последний вариант, желаю объяснить позицию.
AG>Лучшая документация — это сам код. Комментарии для документации читаются не только в документации, но и в коде. AG>Т.к. документация пишется в комментарии, "DSL" для неё имеет только одно техническое требование: чтобы оставался комментарием в соответствующем языке. Чем проще и читабельнее, тем лучше. AG>Вот пример правильного комментария для документации. AG>http://java.sun.com/j2se/javadoc/writingdoccomments/#format AG>Можно ещё упростить: вместо @param p1 использовать @p1 и писать менее развёрнуто. AG>XML же просто замусоривает код своим синтаксическим оверхедом, он не самый лучший язык разметки для данного случая. Convert absloutely everything to XML ?
Описание при помоще XML позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов
Здравствуйте, MxKazan, Вы писали:
MK>Описание при помоще XML позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов
Описание на любом заданном языке разметки позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов.
С Intellisense работает даже такая разметка:
struct Point
{
int x; // абсциссаint y; // ордината
}
Для генерации хелпов — стиль javadoc (использую doxygen).
Здравствуйте, Alexander G, Вы писали:
AG>Лучшая документация — это сам код. Комментарии для документации читаются не только в документации, но и в коде. AG>Т.к. документация пишется в комментарии, "DSL" для неё имеет только одно техническое требование: чтобы оставался комментарием в соответствующем языке. Чем проще и читабельнее, тем лучше. AG>Вот пример правильного комментария для документации. AG>http://java.sun.com/j2se/javadoc/writingdoccomments/#format AG>Можно ещё упростить: вместо @param p1 использовать @p1 и писать менее развёрнуто. AG>XML же просто замусоривает код своим синтаксическим оверхедом, он не самый лучший язык разметки для данного случая. Convert absloutely everything to XML ?
Я вообще считаю этот путь с xml-комментариями в коде неправильным... код замусоривается, да и пригодны такие комментарии только для автоматической генерации статических хелпов. Т.е. только для комментирования готового кода, который долгое время не будет меняться.
У меня давно уже зреет другая идея: в коде пишутся только "ссылки" на комментарии, а сами комментарии живут в отдельных xml/html файлах и образуют доступную для всех разработчиков проекта базу знаний. Пример (для С++, для других языков будет все то же самое )
такие комментарии-ссылки подсвечиваются особым образом, и двойной щелчек (или иное действие) на них приводит к загрузке в специальное окно (закладка в нижней области студии — Output, Find Results...) информации, связанной с этим комментарием. Это полноценный html-редактор, там можно редактировать текст комментария , вводить теги для поиска по тегам, ссылаться на другие топики базы знаний и т.д.
Формат комментария еще не определен — возможно, будет так как в примере, может быть просто GUID топика (хотя это совсем не наглядно), там есть некоторые тонкости.
База знаний строится по принципу иерархического дерева с ориентированными на человека именами узлов (в т.ч. на русском языке), с возможностью поиска по тегам (специальная кнопка на тулбаре, специальный диалог поиска, результаты можно отображать в специальной закладке внизу). Дерево должно быть доступно в студии (закладка в области Class View, Solution Explorer...). Двойным щелчком на узле дерева можно перейти в файл и в позицию файла на соответствующий комментарий-ссылку. Так организуется обратная связи "база — код" (что вообще не сделать с помощью автоматически генерируемых хелпов типа doxygen'а !), а база образует гибрид wiki, аутлайнера и именованной иерархической системы bookmark'ов для всего проекта.
Благодаря тому, что отдельные топики и узлы дерева базы хранятся в маленьких html и xml файлах, база полностью пригодна для существования в системе контроля версий, такой как SVN: апдейт скачивает те файлы, которые были закоммичены другими пользователями, а благодаря текстовому формату возможно автоматическое слияние документов.
Здравствуйте, MxKazan, Вы писали: MK>Описание при помоще XML позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов
XML, особенно в том виде, в каком он используется в C#, слишком уж много оверхеда дает. Мне вот нравится, как в haddock сделано. Пишешь определенного вида комментарий рядом с функцией — он документирует им функцию. Пишешь рядом с типом аргумента — он документирует аргумент.
Здравствуйте, Alexander G, Вы писали:
AG>Здравствуйте, MxKazan, Вы писали:
MK>>Описание при помоще XML позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов
AG>Описание на любом заданном языке разметки позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов.
AG>С Intellisense работает даже такая разметка: AG>
AG>struct Point
AG>{
AG> int x; // абсцисса
AG> int y; // ордината
AG>}
AG>
AG>Для генерации хелпов — стиль javadoc (использую doxygen).
Так ежели у нас по-любому разметка, чем же тогда плох xml? "Лишними" скобками разве что
Здравствуйте, Mr.Cat, Вы писали:
MC>Здравствуйте, MxKazan, Вы писали: MK>>Описание при помоще XML позволяет сделать удобный intelliscence, а также может быть использован для автоматической генерации help'ов
MC>XML, особенно в том виде, в каком он используется в C#, слишком уж много оверхеда дает. Мне вот нравится, как в haddock сделано. Пишешь определенного вида комментарий рядом с функцией — он документирует им функцию. Пишешь рядом с типом аргумента — он документирует аргумент.
Гм. Интересный вариант — избавил бы от необходимости следить, чтобы в тегах <param> были корректные имена.
С другой стороны, тоже не выход — комменты по аргументам захламят описание сигнатуры — будет даже хуже.
Здравствуйте, x-code, Вы писали:
XC>да и пригодны такие комментарии только для автоматической генерации статических хелпов. Т.е. только для комментирования готового кода, который долгое время не будет меняться.
Хм... почему это? Наоборот, внося изменения в код, удобнее по ходу дела подправить расположенные рядом комментарий, чем лезть в какую-то базу.
XC>У меня давно уже зреет другая идея: в коде пишутся только "ссылки" на комментарии, а сами комментарии живут в отдельных xml/html файлах
Не увеличит ли это временные затраты на документирование?
Здравствуйте, x-code, Вы писали:
XC>Здравствуйте, Alexander G, Вы писали:
AG>>Лучшая документация — это сам код. Комментарии для документации читаются не только в документации, но и в коде. AG>>Т.к. документация пишется в комментарии, "DSL" для неё имеет только одно техническое требование: чтобы оставался комментарием в соответствующем языке. Чем проще и читабельнее, тем лучше. AG>>Вот пример правильного комментария для документации. AG>>http://java.sun.com/j2se/javadoc/writingdoccomments/#format AG>>Можно ещё упростить: вместо @param p1 использовать @p1 и писать менее развёрнуто. AG>>XML же просто замусоривает код своим синтаксическим оверхедом, он не самый лучший язык разметки для данного случая. Convert absloutely everything to XML ?
XC>Я вообще считаю этот путь с xml-комментариями в коде неправильным... код замусоривается, да и пригодны такие комментарии только для автоматической генерации статических хелпов. Т.е. только для комментирования готового кода, который долгое время не будет меняться. XC>У меня давно уже зреет другая идея: в коде пишутся только "ссылки" на комментарии, а сами комментарии живут в отдельных xml/html файлах и образуют доступную для всех разработчиков проекта базу знаний. Пример (для С++, для других языков будет все то же самое ) XC>
XC>такие комментарии-ссылки подсвечиваются особым образом, и двойной щелчек (или иное действие) на них приводит к загрузке в специальное окно (закладка в нижней области студии — Output, Find Results...) информации, связанной с этим комментарием. Это полноценный html-редактор, там можно редактировать текст комментария , вводить теги для поиска по тегам, ссылаться на другие топики базы знаний и т.д. XC>Формат комментария еще не определен — возможно, будет так как в примере, может быть просто GUID топика (хотя это совсем не наглядно), там есть некоторые тонкости.
XC>База знаний строится по принципу иерархического дерева с ориентированными на человека именами узлов (в т.ч. на русском языке), с возможностью поиска по тегам (специальная кнопка на тулбаре, специальный диалог поиска, результаты можно отображать в специальной закладке внизу). Дерево должно быть доступно в студии (закладка в области Class View, Solution Explorer...). Двойным щелчком на узле дерева можно перейти в файл и в позицию файла на соответствующий комментарий-ссылку. Так организуется обратная связи "база — код" (что вообще не сделать с помощью автоматически генерируемых хелпов типа doxygen'а !), а база образует гибрид wiki, аутлайнера и именованной иерархической системы bookmark'ов для всего проекта. XC>Благодаря тому, что отдельные топики и узлы дерева базы хранятся в маленьких html и xml файлах, база полностью пригодна для существования в системе контроля версий, такой как SVN: апдейт скачивает те файлы, которые были закоммичены другими пользователями, а благодаря текстовому формату возможно автоматическое слияние документов.
Тоже вариант вариант — со ссылками. Но он требует большого внимания к актуальности документации. Кстати, можно было бы, например, по ссылке не в окно уходить, а сделать что-то вроде смарт-тега. В-общем, да, в целом нравится, но нужна хорошая поддержка IDE, в том числе со слежением за актуальностью — а то взял, грохнул метод, а про коммент забыл.
Здравствуйте, MxKazan, Вы писали: MK>С другой стороны, тоже не выход — комменты по аргументам захламят описание сигнатуры — будет даже хуже.
Чтобы не быть голословным — вот пример.
-- | This is the documentation for the 'f' function
f :: Int -- ^ The 'Int' argument
-> Float -- ^ The 'Float' argument
-> IO () -- ^ The return value
f = <тут уже определение функции>
"--" — Это обычное начало однострочного комментария в хаскеле.
"^" и "|"- Это оверхед от haddock'а (ну кроме необходимости размещать спецификацию функции на нескольких строках).
Здравствуйте, MxKazan, Вы писали:
MK>Так ежели у нас по-любому разметка, чем же тогда плох xml? "Лишними" скобками разве что
Да. И не только лишними скобками, но и лишними буквами и линшими значками больше и меньше.
@param someParameter всё ж хуже @someParameter или someParameter, но лучше XML.
Неужели не хочется, чтобы комментарий для системы документирования оставался комментарием для кода ?
Здравствуйте, MxKazan, Вы писали: MK>Так ежели у нас по-любому разметка, чем же тогда плох xml? "Лишними" скобками разве что
Именно. Лишними скобками, названиями тегов и т.п.
Здравствуйте, Mr.Cat, Вы писали:
MC>Здравствуйте, MxKazan, Вы писали: MK>>С другой стороны, тоже не выход — комменты по аргументам захламят описание сигнатуры — будет даже хуже.
MC>Чтобы не быть голословным — вот пример. MC>
MC>-- | This is the documentation for the 'f' function
MC>f :: Int -- ^ The 'Int' argument
->> Float -- ^ The 'Float' argument
->> IO () -- ^ The return value
MC>f = <тут уже определение функции>
MC>
MC>"--" — Это обычное начало однострочного комментария в хаскеле. MC>"^" и "|"- Это оверхед от haddock'а (ну кроме необходимости размещать спецификацию функции на нескольких строках).
Более реальный вариант:
// Initializes a new instance of the Binding class that binds the indicated control property to the specified data member of the specified data source.
// Optionally enables formatting, propagates values to the data source based on the specified update setting, and sets the property to the specified value
// when a DBNull is returned from the data source.public Binding(
string propertyName, // The name of the control property to bind.
Object dataSource, // An Object representing the data source.string dataMember, // The property or list to bind to.bool formattingEnabled, // true to format the displayed data; otherwise, false.
Object nullValue // The Object to be applied to the bound control property if the data source value is DBNull.
)
Не улавливаю, чем это лучше XML'а?
Как быть, если у меня будет длинный тип параметра и длинное имя.
Как быть, если я в описании функции захочу сослаться на параметр?
MK>// Initializes a new instance of the Binding class that binds the indicated control property to the specified data member of the specified data source.
MK>// Optionally enables formatting, propagates values to the data source based on the specified update setting, and sets the property to the specified value
MK>// when a DBNull is returned from the data source.
MK>public Binding(
MK> string propertyName, // The name of the control property to bind.
MK> Object dataSource, // An Object representing the data source.
MK> string dataMember, // The property or list to bind to.
MK> bool formattingEnabled, // true to format the displayed data; otherwise, false.
MK> Object nullValue // The Object to be applied to the bound control property if the data source value is DBNull.
MK>)
MK>
MK>Не улавливаю, чем это лучше XML'а?
Это читается легче, читатель имеет дело только с синтаксисом языка и человеческим языком, но не с синтаксисом докогенерилки.
MK>Как быть, если у меня будет длинный тип параметра и длинное имя.
Писать столько строк, сколько надо.
MK>Как быть, если я в описании функции захочу сослаться на параметр?
так и сылаться, без разметки, это забота генерилки ловить ссылки.
Здравствуйте, x-code, Вы писали:
XC>У меня давно уже зреет другая идея: в коде пишутся только "ссылки" на комментарии, а сами комментарии живут в отдельных xml/html файлах и образуют доступную для всех разработчиков проекта базу знаний.
Ну, в шарпе как раз таки такая возможность есть. Редактор для отдельных файлов к студии прикрутить совсем несложно.
... << RSDN@Home 1.2.0 alpha 4 rev. 1111 on Windows Vista 6.0.6001.65536>>
MK>// Initializes a new instance of the Binding class that binds the indicated control property to the specified data member of the specified data source.
MK>// Optionally enables formatting, propagates values to the data source based on the specified update setting, and sets the property to the specified value
MK>// when a DBNull is returned from the data source.
MK>public Binding(
MK> string propertyName, // The name of the control property to bind.
MK> Object dataSource, // An Object representing the data source.
MK> string dataMember, // The property or list to bind to.
MK> bool formattingEnabled, // true to format the displayed data; otherwise, false.
MK> Object nullValue // The Object to be applied to the bound control property if the data source value is DBNull.
MK>)
MK>
MK>Не улавливаю, чем это лучше XML'а?
Меньше писать, меньше читать. При этом выразительность не страдает.
MK>Как быть, если у меня будет длинный тип параметра и длинное имя.
ССЗБ. Еще один повод использовать удобочитаемые и удобонаписаемые (ака в меру короткие) имена.
MK>Как быть, если я в описании функции захочу сослаться на параметр?
Забота самого "документатора". Хотя в haddock вроде такого нет. Впрочем — и не особо надо. Описание параметра и так будет в пределах досягаемости — от гиперссылки пользы не будет.
Здравствуйте, Mr.Cat, Вы писали:
MK>Не улавливаю, чем это лучше XML'а? MC>Меньше писать, меньше читать. При этом выразительность не страдает.
Сейчас сигнатура не смешивается с каментами. А предлагается наоборот, всё в одну кучу свалить.
Подобный вариант также вынуждает каждый параметр писать с новой строки.
MK>>Как быть, если я в описании функции захочу сослаться на параметр? MC>Забота самого "документатора". Хотя в haddock вроде такого нет. Впрочем — и не особо надо. Описание параметра и так будет в пределах досягаемости — от гиперссылки пользы не будет.
И в С# ссылки не будет. Дело в том, что по итоговому форматированию в хелпе можно понять, что подразумевается под словом в предложении — термин или имя параметра.
Здравствуйте, MxKazan, Вы писали: MK>Сейчас сигнатура не смешивается с каментами. А предлагается наоборот, всё в одну кучу свалить.
Сейчас — это где? Я привел пример того, как при использовании haddock описание смешивается с сигнатурой. По-моему получается неплохо.
MK>Подобный вариант также вынуждает каждый параметр писать с новой строки.
Вы так говорите, как будто это что-то плохое.
Здравствуйте, Mr.Cat, Вы писали:
MC>Здравствуйте, x-code, Вы писали:
XC>>да и пригодны такие комментарии только для автоматической генерации статических хелпов. Т.е. только для комментирования готового кода, который долгое время не будет меняться. MC>Хм... почему это? Наоборот, внося изменения в код, удобнее по ходу дела подправить расположенные рядом комментарий, чем лезть в какую-то базу.
XC>>У меня давно уже зреет другая идея: в коде пишутся только "ссылки" на комментарии, а сами комментарии живут в отдельных xml/html файлах MC>Не увеличит ли это временные затраты на документирование?
Я это представляю так: создаю новый метод (или вижу старый, без документации). Тыкаю мышью в точку, в которой должен быть комментарий-ссылка, и нажимаю специальную кнопку на тулбаре, или выбираю команду из контекстного меню, или нажимаю сочетание клавиш (насколько я понимаю, API аддинов к современным студиям все это позволяет). Тут же открывается модальное окно, в котором мне предлагается выбрать позицию комментария к дереву (причем дерево уже раскрыто в той же позиции, что и дерево базы на закладке рядом с Class View). Я выбираю родительский узел, корректирую имя нового узла (которое по умолчанию устанавливается в имя объекта под курсором — простейший парсинг одной строки кода!) и нажимаю ОК, тут же диалог закрывается и открывается редактор html в нижней части студии.
Затраты минимальны (клик — выбор в дереве — клик), если учесть что не под диктовку код пишу, а думаю... А для таких языков как C# можно отказаться даже от выбора узла дерева, сделав вариант дерева, соответствующего естественной иерархии пространств имен и классов проекта. Это будет другая кнопка на тулбаре — и всего один клик.
Здравствуйте, MxKazan, Вы писали:
MK>Тоже вариант вариант — со ссылками. Но он требует большого внимания к актуальности документации. Кстати, можно было бы, например, по ссылке не в окно уходить, а сделать что-то вроде смарт-тега. В-общем, да, в целом нравится, но нужна хорошая поддержка IDE, в том числе со слежением за актуальностью — а то взял, грохнул метод, а про коммент забыл.
Сделать функцию "поиска битых ссылок" — не проблема А вообще, я не планирую зацикливаться на комментировании кода, см. здесь
.
В случае если метод грохнули а комментарий забыли — скорее всего будет меняться статус комментария, что визуально будет выглядеть как другая пиктограмма узла в дереве. А при отображении дерева можно будет пользоваться каким-то фильтром — какие узлы показывать: комментарии к коду, свободные комментарии, комментарии к удаленному коду, векторные диаграммы UML (их тоже много!), векторные диаграммы MindMaps, таблицы, ссылки на внешние файлы и т.д...