Каким должен быть язык программирования? Анализ и критика Описание языка Компилятор
Отечественные разработки Cтатьи на компьютерные темы Компьютерный юмор Новости и прочее

Комментарии автоматической генерации документации

В некоторых языках, появившихся относительно недавно,
появились комментарии автоматической генерации документации. В языке Java этот вид комментариев начинаются символами «/**» и заканчиваются символами «*/». В Python такие комментарии начинаются и заканчиваются тремя двойными апострофами «"».

       Такой подход — хорошая идея. Если такие комментарии документирования можно использовать как help, то это просто здорово! Употреблённые внутри функции, они попадают в справку для этой функции. Если такой вид комментария встречается внутри класса, то он попадает в справку для этого класса. Пример на Python:

def DumpOpen(file):
	"""
        Takes one argument (the input file) and opens it for reading
        Returns a list full of data
        """
	openedFile = open(file, "r")
	data = openedFile.readlines()
	cleanedData = []
	for line in data:
		cleanedData.append(line.rstrip())
	openedFile.close()
	return cleanedData

       В программе на языке Java комментарии документации могут появляться перед классом, объявлением интерфейса, методом, конструктором или объявлением поля. На основе этих комментариев может быть сгенерирована (как вариант) web-страница с документацией.

       Отказываться от такого удобства в будущих языках программирования неразумно.

Опубликовано: 2012.09.25, последняя правка: 2014.12.20    10:39

ОценитеОценки посетителей
   █████████████████████████ 6 (60%)
   ▌ 0
   █████ 1 (10%)
   █████████████ 3 (30%)

Отзывы

✅  2012/10/05 08:24, utkin          #0 

В C# также есть подобные комментарии.

✅  2016/03/20 10:49, rst256          #1 

Doxygen, а лучше CWEB хотя CWEB это уже совсем иной взгляд на документирование кода.

✅  2016/03/21 14:28, Автор сайта          #2 

Doxygen .. работает подобно компилятору, анализируя исходные тексты и создавая документацию.

Т.е. в него надо ещё свой анализатор вкладывать, настраивать на свой язык? А если основной формой хранения программы будет некое нетекстовое промежуточное представление, то будут сложности?

✅  2016/08/06 18:55, rst256          #3 

А если основной формой хранения программы будет некое нетекстовое промежуточное представление, то будут сложности?

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

✅  2021/03/27 12:32, Виталий Монастырский          #4 

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

✅  2021/04/01 13:26, Александр Коновалов aka Маздайщик          #5 

Если честно, то я лично не понимаю — а почему для этих целей нельзя использовать обычные многострочные комментарии, ведь они для того и пишутся, чтобы документировать код???

Разные цели документирования: можно документировать интерфейс или реализацию. Документация интерфейса — это то, как пользоваться некоторой сущностью (функцией, классом, модулем, библиотекой…), она не касается того, как устроена сущность. Документация реализации — так как эта сущность устроена. Первая документация нужна, если мы просто хотим вызывать некоторую функцию, вторая — если мы хотим саму функцию модернизировать. И первое требуется гораздо чаще, чем второе.

Например, для функции сортировки нам нужно знать, как передавать ей набор сортируемых объектов, как передавать критерий сортировки, как получается результат (набор переупорядочивается на месте или строится новая коллекция, уже отсортированная), стабильна сортировка или нет, какая асимптотика алгоритма. Этого всего нам достаточно, чтобы написать вызов функции sort().

А какой алгоритм реализован внутри функции сортировки, нам нужно знать только на момент написания этой функции. Или оптимизации, если выяснится, что программа тормозит из-за медленной сортировки.

Поэтому разумно разделять два вида комментариев и для комментариев интерфейса формировать документ с описанием API (например, в виде HTML).

Для некоторых языков особые документирующие комментарии могут быть избыточны. Например, для языка Си документирующие комментарии можно размещать в .h-файле, а комментарии реализации — в .c. Для Java, наоборот, нужны, т.к. отдельных файлов, где описывается интерфейс, в Java нет.

Добавить свой отзыв

Написать автору можно на электронную почту
mail(аt)compiler.su

Авторизация

Регистрация

Выслать пароль

Карта сайта


Содержание

Каким должен быть язык программирования?

Анализ и критика

●  Устарел ли текст как форма представления программы

●  Русский язык и программирование

●  Многоязыковое программирование

Синтаксис языков программирования

Синтаксический сахар

●  Некоторые «вкусности» Алгол-68

●  «Двухмерный» синтаксис Python

●  Почему языки с синтаксисом Си популярнее языков с синтаксисом Паскаля?

●  Должна ли программа быть удобочитаемой?

●  Стиль языка программирования

●  Тексто-графическое представление программы

●●  Разделители

●●  Строки программы

●●  Слева направо или справа налево?

●  Комментарии

●●  Длинные комментарии

●●  Короткие комментарии

●●  Комментарии автоматической генерации документации

●●  Нерабочий код

●●  Помеченные комментарии

●  Нужны ли беззнаковые целые?

●  Шестнадцатиричные и двоичные константы

●  Условные операторы

●  Переключатель

●  Циклы

●●  Продолжение цикла и выход из него

●  Некошерный «goto»

●  Изменение приоритетов операций

●  Операции присвоения и проверки на равенство. Возможно ли одинаковое обозначение?

●  Так ли нужны операции «&&», «||» и «^^»?

●  Постфиксные инкремент и декремент

●  Почему в PHP для конкатенации строк используется «.»?

●  Указатели и ссылки в C++

●●  О неправомерном доступе к памяти через указатели

●  Обработка ошибок

●  Функциональное программирование

●●  Нечистые действия в чистых функциях

●●  О чистоте и нечистоте функций и языков

●●  Макросы — это чистые функции, исполняемые во время компиляции

●●  Хаскелл, детище британских учёных

●●  Измеряем замедление при вызове функций высших порядков

●●  C vs Haskell: сравнение скорости на простом примере

●●  Уникальность имён функций: за и против

●●  Каррирование: для чего и как

●●  О тестах, доказывающих отсутствие ошибок

●  Надёжные программы из ненадёжных компонентов

●●  О многократном резервировании функций

●  Оценка надёжности функции с несколькими реализациями

●  Использование памяти

●  Почему динамическое распределение памяти — это плохо

●  Как обеспечить возврат функциями объектов переменной длины?

●●  Типы переменного размера (dynamically sized types, DST) в языке Rust

●●  Массивы переменной длины в C/C++

●●  Размещение объектов в стеке, традиционный подход

●●  Размещение объектов переменной длины с использованием множества стеков

●●  Размещение объектов переменной длины с использованием двух стеков

●●  Реализация двухстековой модели размещения данных

●●  Двухстековая модель: тесты на скорость

●●  Изменение длины объекта в стеке во время исполнения

●●  Размещение объектов переменной длины с использованием одного стека

●  Можно ли забыть о «куче», если объекты переменной длины хранить в стеке

●  Безопасность и размещение объектов переменной длины в стеке

●  Массивы, структуры, типы, классы переменной длины

●  О хранении данных в стеке, вместо заключения

●  Реализация параметрического полиморфизма

Описание языка

Компилятор

Отечественные разработки

Cтатьи на компьютерные темы

Компьютерный юмор

Новости и прочее




Последние отзывы

2024/11/02 02:09 ••• Иван
Энтузиасты-разработчики компиляторов и их проекты

2024/11/01 12:11 ••• ИванАс
Русской операционной системой должна стать ReactOS

2024/10/28 00:00 ••• alextretyak
Продолжение цикла и выход из него

2024/10/27 21:54 ••• ИванАс
Новости и прочее

2024/10/27 14:01 ••• Автор сайта
О русском ассемблере

2024/10/19 23:12 ••• Автор сайта
Русский язык и программирование

2024/10/25 01:34 ••• Владимир
Оценка надёжности функции с несколькими реализациями

2024/09/29 23:40 ••• Автор сайта
Десятка худших фич C#

2024/09/29 13:10 ••• Автор сайта
ЕС ЭВМ — это измена, трусость и обман?

2024/09/22 21:08 ••• Вежливый Лис
Бесплатный софт в мышеловке

2024/09/05 17:44 ••• Автор сайта
Правила языка: алфавит

2024/09/04 00:00 ••• alextretyak
Циклы

2024/09/02 22:24 ••• Автор сайта
Постфиксные инкремент и декремент