Описание тега self-documenting-code
2
ответа
PHP: использование ключей массива для определения аргументов функции
Я определяю пользователя многими функциями, и у некоторых из них есть шесть, десять или даже больше аргументов. Чтение моего кода становится затруднительным, когда я забываю, каковы аргументы функции или в каком порядке они идут. Я разработал способ…
08 авг '18 в 16:45
1
ответ
Использование утилиты sphinx-apidoc от Sphinx для автоматической генерации документации из кода Python
Мне интересно, что такое формат комментариев, чтобы иметь самодокументируемый код с помощью утилиты sphinx-apidoc Sphinx. Я могу получить эту утилиту для генерации набора файлов reStructuredText для каждого файла python, но эти файлы еще нужно запол…
26 сен '13 в 20:03
5
ответов
Как автоматически сгенерировать документацию API из картографических маршрутов Express?
Я разрабатываю REST API в nodejs + Express, и я одновременно документировал свой API в файле README, и мне было интересно, возможно ли его автоматизировать. например, дано: app.get('/path/to', dosomething); app.post('/path/to/:somethingelse', scream…
05 сен '12 в 23:44
1
ответ
Самодокументируемые параметры в Lua
Я ищу способ прояснить контракты моих функций Lua. В частности, какие атрибуты там должны иметь параметры. Чтобы проиллюстрировать мою проблему, некоторые фрагменты кода с типичной структурой моего текущего кода. Функция, которая создает новый "экзе…
16 окт '16 в 07:06
15
ответов
В Python, как мне указать, что я переопределяю метод?
В Java, например, @Override аннотация не только обеспечивает проверку переопределения во время компиляции, но и обеспечивает отличный самодокументирующийся код. Я просто ищу документацию (хотя, если это индикатор какой-то проверки, такой как pylint,…
22 июл '09 в 19:26
1
ответ
Стоит ли самодокументируемый код потенциальных проблем с производительностью?
Я создал небольшой класс, который позволяет мне использовать перечислители строго типизированных перечислений в качестве флагов (в комбинации). Я использую type_traits для определения базового типа, поэтому он также должен быть слегка безопасным для…
02 авг '12 в 15:52
2
ответа
Должны ли комментарии метода / класса применяться последовательно или только по необходимости?
Для согласованности я всегда применял комментарии (в форме JavaDoc) ко всем методам и классам, даже если они являются простыми методами получения и установки или очень маленькими классами-обертками. Но я также стремлюсь написать самодокументированны…
18 сен '10 в 08:40
1
ответ
Есть ли у Kotlin метки method-CALL?
Я переезжаю из Свифта в Котлин и до сих пор люблю это. Тем не менее, я привык объявлять такие методы (притворяться, что указанные методы существуют и работают): // Swift method declaration func drawCircle(inRect rect: CGRect, antialiased: Bool) { su…
20 авг '16 в 00:25
1
ответ
JavaScript Самодокументированный код, где инструменты API Docs?
Эти две концепции кажутся нелогичными. Есть одна сторона аргумента, которая видит вред, который комментарии наносят читабельности, и нарушениям DRY (если комментарии даже обновляются). Однако переверните монету, и вам необходимо предоставить хорошую…
17 мар '11 в 17:50
1
ответ
Оптимизируют ли самые современные компиляторы JavaScript/ECMAScripte ненужное присвоение переменных при возврате значения из вызова функции?
Скажем, мы внутри объекта, который реализует обработку файлов. Я хочу написать код для удобства чтения. Пример кода, в котором может быть сложно определить тип возвращаемого значения, особенно при наличии нескольких вызовов вложенных функций: functi…
26 июл '17 в 09:49
2
ответа
Jira JQL может иметь встроенные / встроенные комментарии?
Я нашел хороший список руководств по JQL, включая ссылку на то, как написать плагин [1]. Уже есть или можно добавить комментарии к JQL-запросу? Например, чтобы задокументировать мой предмет, я хотел бы иметь возможность задокументировать, что наш но…
30 мар '15 в 16:35
20
ответов
Люди используют Венгерские Соглашения об именах в реальном мире?
Стоит ли изучать конвенцию или это вред от читабельности и ремонтопригодности?
07 авг '08 в 22:31
2
ответа
Самодокументируемый asp.net api
Я создал API Asp.net в VS2015. Внутри Области>HelpPage>App_Start>HelpPageConfig.cs Я раскомментировал строку 37 config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml"))); В папке …
31 июл '17 в 19:50
1
ответ
Как мне сказать doxygen, что функция "самодокументируется"?
Я использую Doxygen для моего (C++) проекта. У меня есть некоторые функции, которые не требуют пояснений, для которых я не хочу добавлять какие-либо комментарии или объяснения, но которые я хочу добавить в документацию. Теперь, это происходит как ст…
15 май '19 в 10:36
0
ответов
Как использовать самодокументирующийся спецификатор равенства (отладки) с str.format ()?
Представлен Python 3.8 =спецификатор в f-строках (см. эту проблему и запрос на вытягивание). Это позволяет быстро представить как значение, так и имя переменной: from math import pi as π f'{π=}' # 'π=3.141592653589793' Я хотел бы использовать эту фу…
27 июл '20 в 21:24
0
ответов
C/C++, документирование структуры внутри структуры для Doxygen
Я новичок в doxygen. Я пытаюсь задокументировать некоторые библиотеки для нашего модуля Onethinx LoRaWAN. Мы используем структуру внутри структуры внутри объединения для передачи некоторых данных между двумя ядрами (ARM Cortex M4 и M0+). Конструкции…
12 янв '21 в 19:00
0
ответов
Инструмент документирования самого языка программирования
Сначала я думал об использовании doxygen для своих нужд, но потом понял, что было бы лучше иметь какой-нибудь онлайн-инструмент с открытым исходным кодом для описания самого языка программирования. Например, официальная документация PHP выглядит иде…
01 май '23 в 23:12
0
ответов
Что такое подсказка типа (или аннотация типа) подсказок типа (или аннотаций типа)
Рассмотрим следующий код: from typing import Union # (or any other type hint, type Alias, etc.) def func(arg: ???) -> None: pass func(Union[tuple[int, ...], float, "MyClass"]) class MyClass(object): pass Аргумент функции func — это подсказка типа…
05 июн '23 в 09:39