=====================================================
|
Описание | public void Fun1()
метода | {
editable | }
|
|
|
|
=====================================================
Т.е. чтобы xml-комментарии отделить от кода, и тем не менее чтобы они всегда были под рукой, т.е. чтобы не нужно было открывать спец. окно для написания комментов а интегрировать окно для написания кода и комментов. Но чтобы котлеты (код) отдельно, комменты (мухи) отдельно.
Основной минус того что есть сейчас -- размазывается обзор. Часто мне и так понятно что делает код и комменты только мешают. Из названий параметров я и так понимаю что за значение передается. А xml-комменты закрывают пол экрана. Некоторые любят на целый экран писать. Ну мешает же...
Выход -- xml-комменты должны быть в отдельных xml-файлах, но чтобы не было соблазна их не писать, окошко для написания комментов должно быть все время под рукой. Для этого разделяем окно редактора на 2 части (ессестно, можно мышкой менять ширину фрейма или вообще закрыть) и во второй части пишем комменты. Притом там можно автоматом генерить поля для каждого метода: для общего описания, параметров, возращаемого значения и пр.
Если вы работаете с кодом -- комменты вам постоянно не нужны -- вы и так помните все. А если нужно писать комменты -- просто растягиваете левое окошко и в авто-сгенеренном шаблоне все пишите.
Не оно. Не прятать комменты под значком, т.к. иногда их все нужно видеть и читать.
Хочется именно читать чистый код и читать чистые комменты. Могу закрыть код и читать просто xml-комменты, могу наоборот. Можно сузить комменты и читать одновременно.
Можно скомпилить код и передать другому чтобы он писал xml-комменты. При этом ему не нужно давать исходники. И потом я смогу все видеть с привязкой к коду.
Вообще речь именно об xml-комментах, на основе которых генерится документация. Почему они должны быть в коде?
Здравствуйте, Shmj, Вы писали:
S>Основной минус того что есть сейчас -- размазывается обзор. Часто мне и так понятно что делает код и комменты только мешают. Из названий параметров я и так понимаю что за значение передается. А xml-комменты закрывают пол экрана.
xml-комменты можно положить в отдельный файл и сослаться на него из кода. А полный хелп смотреть по Ctrl+Q решарпером. Так что все, что ты хочешь есть, правда не в разделенном экране, а в попапе.
... << RSDN@Home 1.0.0 alpha 5 rev. 0 on Windows 8 6.2.9200.0>>
Здравствуйте, AndrewVK, Вы писали:
AVK>xml-комменты можно положить в отдельный файл и сослаться на него из кода. А полный хелп смотреть по Ctrl+Q решарпером. Так что все, что ты хочешь есть, правда не в разделенном экране, а в попапе.
Ключевое слово СМОТРЕТЬ. А нужно не смотреть а ПИСАТЬ. И чтобы ничего дополнительно указывать не нужно было -- иначе лень.
И обязательно в том же окне, чтобы ничего не нужно было дополнительно открывать -- иначе лень.
Т.е. такие условия:
1. Раздельное окно в левой части пишем xml-комменты (можно сразу в человеческом виде, а не в XML), в правой код. Ширину фрейма можно изменять.
2. При прокрутке кода прокручиваются и комменты.
3. Комменты привязаны к методам. Т.е. слева напротив метода будет коммент именно к этому методу.
4. Можно как читать так и писать. Причем писать в удобном виде: форма-шаблон для метода, для свойства и пр.
5. Комменты полностью отделены от кода. Можно написать их и для dll-ки, причем когда смотрите код оно все автоматически будет сопоставлено для открытых методов.
Согласитесь -- идея просто гениальна. И революционна. В будущем 100% будет именно так.
Просто обидно что ее придумал какой-то незначительный я, а не MS Research.
Re[3]: А вот еще одна революционная идея (xml-комментарии)
Здравствуйте, VladD2, Вы писали:
S>>А нужно не смотреть а ПИСАТЬ. И чтобы ничего дополнительно указывать не нужно было -- иначе лень.
VD>А зачем смотреть на хэлп когда пишешь метод?
Смотреть как раз не нужно. По этому должна быть возможность прикрыть фрейм с комментами, если вы их писать не будете. В текущей реализации Visual Studio все смешано -- и код и XML-комменты и прикрыть вы ничего не можете.
Вы как сейчас XML-комменты пишите?
Кто-то пишет сначала код, потом XML-комменты после отладки. В таком случае просто прикрываете фрейм с XML-комментами и видите только код. Когда код отладили -- открываете фрейм с XML-комментами (с кодом можете вообще закрыть) и пишите xml-комменты. Обычные комменты (не для генерации доки которые) сюда не входят -- они как и ранее в коде.
Если же вы пишите и код и XML-комменты одновременно -- то у вас будет постоянно открыто 2 фрейма.
Здравствуйте, Shmj, Вы писали:
S>Вы как сейчас XML-комменты пишите?
Когда понимаю, что метод будет использоваться публично, то пишу док-коменты. Правильные коменты — это хорошие названия функций и параметров.
S>Если же вы пишите и код и XML-комменты одновременно -- то у вас будет постоянно открыто 2 фрейма.
У меня как-то редко получается законченный вариант API с первого раза. Обычно все рефакторится по сто раз. При этом док-коменты создают только проблемы (их надо обновлять). Вот когда API стабилизируется и я понимаю, что им будут пользоваться незнакомые с кодом люди, то можно и док-коменты добавить.
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Re[6]: А вот еще одна революционная идея (xml-комментарии)
Здравствуйте, VladD2, Вы писали:
VD>У меня как-то редко получается законченный вариант API с первого раза. Обычно все рефакторится по сто раз. При этом док-коменты создают только проблемы (их надо обновлять). Вот когда API стабилизируется и я понимаю, что им будут пользоваться незнакомые с кодом люди, то можно и док-коменты добавить.
А вам не мешает то XML-комментарии прямо в коде? Т.е. вам нужно лишний раз пролистывать код, чтобы перейти от ненужного для вас текста комментария к коду функции и что-то там подправить.
Меня лично это напрягает и намного удобнее было бы отделить комментарии от кода, но оставить связанность и возможность видеть и изменять все на одном экране без лишних действий.
Re[3]: А вот еще одна революционная идея (xml-комментарии)
Здравствуйте, AndrewVK, Вы писали:
AVK>Ну так открываешь файлик с комментами и пишешь, в чем проблема то?
А вы как пишите сейчас? В отдельном файлике или прямо в коде?
Смотрел вашу CodeJam -- там все прямо в коде. И знаете почему? Потому что лень:
1. Прописывать путь к отедельному файлику с комментами каждый раз.
2. Потом еще его и октрывать каждый раз.
3. Потом находить где в этом файлике описание метода, на который вы сейчас смотрите в коде.
4. Потом вручную пересматривать весь XML и смотреть какие методы были изменены/удалены.
5. Да еще и в XML-формате писать.
По этому вы тупо пишите прямо в коде, замусоливая код длинными комментами.
S>>И обязательно в том же окне AVK>А это уже субъективная вкусовщина.
Нет. Это главная причина называлась -- если комменты нужно писать в отдельном от кода окне -- то их писать не будут.
Ключевая позиция -- оно должно быть одно и то же, но разделенное.
S>>Согласитесь -- идея просто гениальна. И революционна. В будущем 100% будет именно так. AVK>Не соглашусь.
А когда это сделают MS -- вы будете говорить что стало намного удобнее и идея сама по себе гениальна. Когда же я напомню вам что придумал я -- вы пожмете плечами вот так
Re[2]: А вот еще одна революционная идея (xml-комментарии)
Здравствуйте, IT, Вы писали:
IT>С этим в форум по Немерле, там тебе макрос напишут и всё.
Не, тут нужно писать расширение для Visual Studio. Причем не тривиальное, хотел найти похожее с открытым кодом, чтобы на его основе сделать -- не нашлось.
Было бы еще время -- недели за 3, быть может, это можно реализовать. Уверен что в будущем MS и другие именно такой способ документирования кода и применят. Но есть риск что денег в этого не поимеешь -- просто спасибо скажут или тупо проигнорят. Так что стремно начинать.
Здравствуйте, Shmj, Вы писали:
AVK>>Ну так открываешь файлик с комментами и пишешь, в чем проблема то? S>А вы как пишите сейчас? В отдельном файлике или прямо в коде?
Зависит от задачи и текущего этапа. Если просто предварительные комментарии — прямо в коде. Если подготавливается документация — объемные вещи выносятся в файлики.
S>Смотрел вашу CodeJam -- там все прямо в коде. И знаете почему? Потому что лень:
Нет, потому что так лучше.
S>>>И обязательно в том же окне AVK>>А это уже субъективная вкусовщина. S>Нет.
Да.
S>>>Согласитесь -- идея просто гениальна. И революционна. В будущем 100% будет именно так. AVK>>Не соглашусь. S>А когда это сделают MS -- вы будете говорить что стало намного удобнее и идея сама по себе гениальна.
Вот когда сделают, тогда и поговорим. А пока не делают и планов таких нет.
... << RSDN@Home 1.0.0 alpha 5 rev. 0 on Windows 8 6.2.9200.0>>
1. Возможность редактировать комментарии и код одновременно. Причем не в XML-виде а в человеческом.
2. Возможность редактировать код без комментариев, чтобы они не мешали.
3. Возможность редактировать только комментарии (без кода), чтобы код не мешал. Но при этом чтобы была возможность быстро взглянуть на код, если что-то подзабыл.
Если нам не помогут, то мы тоже никого не пощадим.
