Обогащенный текст помог бы прокомментировать код? [закрытый]

я предпочел бы иметь только javadoc богатые элементы, как, ссылки на классы, заголовки и такой представленный богатым-texty способом. это было бы преобразовано прозрачно в javadoc HTML. я думаю, что это - хорошая идея для язя.

Вы могли проверить phpdoc используемый формат - в основном он использует теги для маркировки содержания, но может содержать ссылки и т.д.

Единственный обогащенный текст, которого я действительно требую в комментариях, является гиперссылками для ссылки на другие части кода. Это довольно легко выполнить с комментариями Javadoc-стиля, или только с ctags.

Если комментарии простого текста не являются четкими, Вам, вероятно, нужна лучшая документация, не лучшее форматирование документации.

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

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

Это не работало бы, пока это не была часть общего и широко используемого IDE, как бы то ни было.

Абсолютно нет! Я просто не доверяю никому для слоняний без дела в моем коде со "специальными символами", которые могут, когда-нибудь, дать мне другой источник головных болей.

Обновление: Jeremy указывает, что комментарии - включая любое форматирование - всегда разделялись бы, прежде чем файл был отправлен компилятору. Это прекрасно, но мне все еще внутренне не нравится идея поместить управляющие символы в мой код.

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

Так снова: не изменяйте мой формат файла. Но выделение материала на основе содержания прекрасно.

Структура, которую я хочу документации, не соответствует структуре исходного кода.

Например, функциональная спецификация является списком функций: каждая функция описана в одном месте..., но реализация функции, например, как транзакция от UI до базы данных через DAL, не находится в одном месте в исходном коде.

Кроме того, различные люди хотят различные типы документации:

• Какова функциональная спецификация?
• Каков UI?
• Каков дизайн данных?
• Какова разработка программного обеспечения?
• Каков проект разработки / процесс?
• Каков тестовый сценарий?
• Каков результат испытаний?

Документация Puting в тех же исходных файлах как исходный код не помогает, imo.

Однако см. также "грамотное программирование". Я не знаю то, что "грамотное программирование" или было предназначено, чтобы быть, но это выглядит полезным по крайней мере в одном узком случае, который является, когда Вы пытаетесь записать о программном обеспечении (например, написать статью о некотором программном обеспечении).

Javadoc позволил HTML-тэги и набор пользовательских тегов (например, связываться с другими классами или методами) в течение прошлого десятилетия.

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

Однако я могу понять настраиваемое автоформатирование для Вашего IDE. Например, Ваш IDE мог быть настроен для обработки комментариев под Скидкой с цены (который StackOverflow использует), который обладает преимуществом наличия читаемого "кода".

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

final ключевое слово может покончить с этим типом комментария:

// Don't extend this class! Ever!

Абстрактные методы заменяют это:

// make sure you implement foo() bar() and baz() in all child classes

И хорошее объектно-ориентированное программирование организует код так, чтобы Вам не были нужны большие раздражающие заголовки:

// *******************************************
// ***** Input Handling here *****************
// *******************************************
// * This next section has all the functions *
// * dealing with keyboard input.            *
// *******************************************

... становится...

class InputHandler {
    // This class deals with keyboard input.
}

Обычно идея прокомментировать Ваш код состоит в том, чтобы объяснить, какого действия Ваши отдельные стандартные программы (или составные части) предназначаются для достижения. Вы не должны должны быть повышать те комментарии с дополнительным форматированием и что другие могли бы рассмотреть помехой.

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

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

Один смог обходить эту проблему, ЕСЛИ вся команда приняла обогащенный текст, редактируя IDE. Но Вы были бы, начиная храбрую, новую методологию создания кода, что-то, чего большинство команд мудро склонно избегать в пользу адаптации текущих лучших практик.

Фактическая встроенная документация является другим вопросом, и я не уверен лучший способ иметь дело с этим.

Взгляните на Visual Studio 2010, у нее есть пример расширения, которое вставляет изображения в файлы кода .

В те времена, когда NeXT поддерживал свою собственную частную ветвь GCC, он разрешал использование тегов RTF в исходном коде. Не только в комментариях, а везде. Это никогда не было широко используемой функцией, и в конце концов от нее отказались. Одна из проблем заключалась в том, что RTF действительно трудно читать с помощью текстового редактора, поэтому он работал, только если все в команде использовали редактор с поддержкой RTF (и инструмент сравнения).

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

В код Python уже можно поместить форматированный текст: sphinx . По крайней мере, в виде RST. И на самом деле нет необходимости использовать для этого IDE (хотя я полагаю, что некоторая помощь по форматированию будет полезна).