Исчерпывающее руководство по документированию кода на Python

Добро пожаловать в полное руководство по документированию кода на Python. Независимо от того, документируете ли вы небольшой скрипт или крупный проект, являетесь ли вы новичком или опытным специалистом по Python, в этом руководстве будет рассказано все, что вам нужно знать. Мы разбили это руководство на четыре основных раздела:

1. Почему важно документировать свой код: введение в документацию и ее важность
2. Комментирование и документирование кода: Обзор основных различий между комментированием и документированием, а также подходящее время и способы использования комментариев.
3. Документирование вашей базы кода Python с помощью DocStrings: Глубокое погружение в DocStrings для классов, методов классов, функций, модулей, пакетов и скриптов, а также в то, что должно быть найдено внутри каждого из них
4. Документирование ваших проектов на Python: необходимые элементы и то, что они должны содержать для ваших проектов на Python

Почему важно документировать свой код

Если вы читаете это руководство, то вероятно задумывались о важности документирования кода. Но если нет, то позвольте мне процитировать то, что Гвидо (создатель Python) упомянул во время недавней конференции PyCon:

"Код чаще читается, чем пишется."

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

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

После поиска вы начинаете понимать, что документация отсутствует или, что еще хуже, отсутствует полностью. Это неприятное чувство, которое удерживает вас от использования библиотеки, независимо от того, насколько велик или эффективен код. Даниэле Прочида лучше всего описал эту ситуацию:

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

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

Комментирование и документирование кода

Прежде чем мы перейдем к тому, как документировать ваш код на Python, нам нужно отличить документирование от комментирования.

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

"Код подсказывает вам, как это сделать, а комментарии - почему."

Документирование кода - это описание его использования и функциональности для ваших пользователей. Хотя это может быть полезно в процессе разработки, основной целевой аудиторией являются пользователи. В следующем разделе описано, как и когда комментировать ваш код.

Основы комментирования кода

Комментарии создаются на Python с использованием знака решетки # и должны быть краткими, не длиннее нескольких предложений. Вот простой пример:

def hello_world():
    # комментарий, предшествующий простому оператору вывода
    print("Привет мир")

Согласно PEP 8, максимальная длина комментариев должна составлять 72 символа. Это верно, даже если в вашем проекте максимальная длина строки превышает рекомендуемые 80 символов. Если объем комментария превышает допустимое количество символов в нем, целесообразно использовать несколько строк для комментария:

def hello_long_world():
    # Очень длинное заявление, которое просто продолжается, и продолжается
    # никогда не заканчивается, пока не будет достигнут лимит в 80 символов
    print("Привееееееееееееееееееееееееееееееееееееееееееееееееееееееееет мир")

Комментирование вашего кода служит нескольким целям, в том числе:

1. Планирование и рецензирование: Когда вы разрабатываете новые части своего кода, может оказаться целесообразным сначала использовать комментарии для планирования или описания этого раздела кода. Не забудьте удалить эти комментарии после того, как сам код будет реализован и проверен/протестирован:

# Первый шаг
# Второй шаг
# Третий шаг

1. Описание кода: Комментарии могут использоваться для объяснения назначения определенных разделов кода:

# Попытайтесь установить соединение на основе предыдущих настроек.
# В случае неудачи запросите у пользователя новые настройки.

1. Описание алгоритма: При использовании алгоритмов, особенно сложных, может быть полезно объяснить, как работает алгоритм или как он реализован в вашем коде. Также может быть уместно описать, почему был выбран определенный алгоритм, а не другой.

# Использование быстрой сортировки для повышения производительности

1. Тегирование: с помощью тегов можно помечать определенные участки кода, в которых обнаружены известные проблемы или области, требующие улучшения. Вот несколько примеров: BUG, FIXME и TODO.

# TODO: Добавьте условие для случаев, когда значение val равно None

Комментарии к вашему коду должны быть краткими и целенаправленными. По возможности избегайте использования длинных комментариев. Кроме того, вам следует придерживаться следующих четырех основных правил, предложенных Джеффом Этвудом:

1. Размещайте комментарии как можно ближе к описываемому коду. Комментарии, которые не соответствуют описываемому коду, раздражают читателя и легко пропускаются при обновлении
2. Не используйте сложное форматирование (например, таблицы или рисунки в формате ASCII). Сложное форматирование отвлекает внимание от содержимого, и со временем его может быть сложно поддерживать.
3. Не включайте избыточную информацию. Предположим, что читатель кода имеет базовое представление о принципах программирования и синтаксисе языка.
4. Создавайте свой код таким образом, чтобы он сам себя комментировал. Самый простой способ понять код - это прочитать его. Когда вы разрабатываете свой код, используя четкие и понятные концепции, читатель сможет быстро понять ваши намерения.

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

Комментирование кода с помощью Type Hinting (Python 3.5+)

Type Hinting был добавлен в Python 3.5 и является дополнительной формой, помогающей читателям вашего кода. Фактически, она выводит четвертое предложение Джеффа, приведенное выше, на новый уровень. Это позволяет разработчику разрабатывать и объяснять части своего кода без комментариев. Вот краткий пример:

def hello_name(name: str) -> str:
    return(f"Привет {name}")

Изучив Type Hinting, вы можете сразу сказать, что функция ожидает, что входное значение будет иметь тип str (строка). Вы также можете сказать, что ожидаемый результат работы функции также будет иметь тип str. Хотя подсказки по типу текста помогают сократить количество комментариев, имейте в виду, что это также может привести к дополнительной работе при создании или обновлении проектной документации.

Документирование вашего кода Python с помощью DocStrings

Теперь, когда мы узнали о комментировании, давайте углубимся в документирование базы кода Python. В этом разделе вы узнаете о DocStrings и о том, как это использовать для документирования. Далее этот раздел разделен на следующие подразделы:

1. Представление о DocStrings: Справочная информация о том, как они работают внутри Python
2. Типы DocStrings: различные типы DocStrings (функция, класс, метод класса, модуль, пакет и скрипт)
3. Форматы DocStrings: Различные форматы DocStrings (Google, NumPy/SciPy, reStructuredText и Epytext)

Представление о DocStrings

Документирование вашего кода на Python сосредоточено на DocStrings. Это встроенные строки, которые при правильной настройке могут помочь вашим пользователям и вам самим в работе с документацией вашего проекта. Наряду с DocStrings, в Python также есть встроенная функция help(), которая выводит объекты DocStrings. Вот краткий пример:

>>> help(str)
Help on class str in module builtins:

class str(object)
 |  str(object='') -> str
 |  str(bytes_or_buffer[, encoding[, errors]]) -> str
 |
 |  Create a new string object from the given object. If encoding or
 |  errors are specified, then the object must expose a data buffer
 |  that will be decoded using the given encoding and error handler.
 |  Otherwise, returns the result of object.__str__() (if defined)
 |  or repr(object).
 |  encoding defaults to sys.getdefaultencoding().
 |  errors defaults to 'strict'.
 # Truncated for readability

Как генерируется этот вывод? Поскольку в Python все является объектом, вы можете просмотреть каталог объекта с помощью команды dir(). Давайте сделаем это и посмотрим, что получится:

>>> dir(str)
['__add__', ..., '__doc__', ..., 'zfill'] # Truncated for readability

В выходных данных этого каталога есть интересное свойство __doc__. Если вы изучите это свойство, то обнаружите следующее:

>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors are specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

Вуаля! Вы нашли, где в объекте хранятся строки документации. Это означает, что вы можете напрямую управлять этим свойством. Однако для встроенных элементов существуют ограничения:

>>> str.__doc__ = "I'm a little string doc! Short and stout; here is my input and print me for my out"
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can't set attributes of built-in/extension type 'str'

Можно манипулировать любым другим пользовательским объектом:

def say_hello(name):
    print(f"Привет {name}, ты меня ищешь?")

say_hello.__doc__ = "Простая функция, которая передает привет..."

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    Простая функция, которая передает привет...

В Python есть еще одна функция, которая упрощает создание docstring. Вместо прямого манипулирования свойством __doc__, стратегическое размещение строкового литерала непосредственно под объектом автоматически установит значение __doc__. Вот что происходит с тем же примером, что и выше:

def say_hello(name):
    """Простая функция, которая передает привет..."""
    print(f"Привет {name}, ты меня ищешь?")

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    Простая функция, которая передает привет...

Вот так! Теперь вы понимаете, что такое строки документации. Теперь пришло время узнать о различных типах строк документации и о том, какую информацию они должны содержать.

Типы DocStrings

Соглашения о строках документации описаны в PEP 257. Их цель - предоставить вашим пользователям краткий обзор объекта. Они должны быть достаточно краткими, чтобы их было легко поддерживать, но в то же время достаточно сложными, чтобы новые пользователи могли понять их назначение и способы использования документированного объекта.

Во всех случаях в DocStrings следует использовать формат строки с тройными и двойными кавычками """. Это следует делать независимо от того, является DocStrings многострочным или нет. Как минимум, DocStrings должен представлять собой краткое изложение того, что вы описываете, и должен содержаться в одной строке:

"""Это краткая сводная строка, используемая в качестве описания объекта."""

Многострочные DocStrings используются для более подробного описания объекта, выходящего за рамки краткого изложения. Все многострочные DocStrings состоят из следующих частей:

1. Сводка в одну строку
2. Пустая строка, продолжающая сводку
3. Какие-либо дальнейшие уточнения для DocStrings
4. Еще одна пустая строка

"""Это сводка

Здесь подпробное описание DocStrings. В этом разделе
вы можете подробнее остановиться на деталях, соответствующих ситуации.
Обратите внимание, что сводка и подробная информация разделены новой пустой строкой.
"""

# Обратите внимание на пустую строку выше. Здесь будет код.

Максимальная длина всех DocStrings должна быть такой же, как и у комментариев (72 символа). DocStrings можно разделить на три основные категории:

1. DocStrings класса: класс и методы класса
2. DocStrings к пакетам и модулям: Пакет, модули и функции
3. DocStrings скрипта: Скрипт и функции

DocStrings класса

DocStrings класса создаются как для самого класса, так и для любых методов класса. Строки документации размещаются непосредственно после класса или метода класса с отступом в один уровень:

class SimpleClass:
    """DocStrings класса будет здесь."""

    def say_hello(self, name: str):
        """DocStrings метода класса будет здесь."""

        print(Привет {name}')

Строки документации класса должны содержать следующую информацию:

1. Краткое описание (сводка) его назначения и поведения
2. Любые публичные методы вместе с кратким описанием
3. Любые свойства (атрибуты) класса
4. Все, что связано с интерфейсом для подклассов, если класс предназначен для создания подклассов

Параметры конструктора класса должны быть задокументированы в строке документации __init__ метода класса. Отдельные методы должны быть задокументированы с использованием отдельных DocStrings. DocStrings метода класса должны содержать следующее:

1. Краткое описание того, что это за метод и для чего он используется
2. Любые передаваемые аргументы (как обязательные, так и необязательные), включая аргументы ключевых слов
3. Пометьте все аргументы, которые считаются необязательными или имеют значение по умолчанию
4. Любые побочные эффекты, возникающие при выполнении метода
5. Любые возникающие исключения
6. Есть ли какие-либо ограничения на то, когда этот метод может быть вызван

Давайте рассмотрим простой пример класса данных, представляющего животное. Этот класс будет содержать несколько свойств класса, свойства экземпляра, __init__ и единственный метод экземпляра:

class Animal:
    """
    Класс используется для описания животного (Animal)

    ...

    Attributes
    ----------
    says_str : str
        формат. строка для вывода того, что говорит животное
    name : str
        имя животного
    sound : str
        звук, который издает животное
    num_legs : int
        количество лап у животного (по умолчанию 4)

    Methods
    -------
    says(sound=None)
        Выводит имя животного и звук который оно издает
    """

    says_str = "{name} говорит {sound}"

    def __init__(self, name, sound, num_legs=4):
        """
        Parameters
        ----------
        name : str
            имя животного
        sound : str
            звук, который издает животное
        num_legs : int, optional
            количество лап у животного (по умолчанию 4)
        """

        self.name = name
        self.sound = sound
        self.num_legs = num_legs

    def says(self, sound=None):
        """Выводит название животного и звук, который оно издает.

        Если параметр `sound` не передан, тогда используется
        звук животного по умолчанию.

        Parameters
        ----------
        sound : str, optional
            звук издаваемый животным (по умолчанию None)

        Raises
        ------
        NotImplementedError
            Если для животного не задан звук или он не
            не передан в качестве параметра.
        """

        if self.sound is None and sound is None:
            raise NotImplementedError("Молчаливые животные не поддерживаются!")

        out_sound = self.sound if sound is None else sound
        print(self.says_str.format(name=self.name, sound=out_sound))

DocStrings к пакетам и модулям

Строки документации к пакету должны быть помещены в верхней части __init__.py файл. В этой строке документации должны быть перечислены модули и подпакеты, которые экспортируются пакетом.

DocStrings модуля аналогичны DocStrings класса. Теперь документируются не классы и методы класса, а сам модуль и все функции, находящиеся в нем. DocStrings модуля помещаются в начало файла даже перед любым импортом. DocStrings модуля должны включать следующее:

1. Краткое описание модуля и его назначение
2. Список любых классов, исключений, функций и любых других объектов, экспортируемых модулем

DocStrings для функции модуля должна содержать те же элементы, что и для метода класса:

1. Краткое описание того, что это за функция и для чего она используется
2. Любые передаваемые аргументы (как обязательные, так и необязательные), включая аргументы ключевых слов
3. Пометьте все аргументы, которые считаются необязательными
4. Любые побочные эффекты, возникающие при выполнении функции
5. Любые возникающие исключения
6. Есть ли какие-либо ограничения на то, когда функция может быть вызвана

DocStrings скрипта

Скрипты считаются отдельными исполняемыми файлами, запускаемыми с консоли. Строки документации для скриптов размещаются в верхней части файла и должны быть достаточно хорошо задокументированы, чтобы пользователи могли в достаточной степени понимать, как использовать скрипт. Он должен быть пригоден для использования в сообщении “usage”, когда пользователь неправильно вводит параметр или использует опцию -h.

Если вы используете argparse, то вы можете пропустить документацию по конкретным параметрам, предполагая, что она правильно задокументирована в параметре help функции argparser.parser.add_argument. Рекомендуется использовать __doc__ в качестве параметра description в конструкторе argparse.ArgumentParser.

Наконец, в DocStrings должен быть указан любой пользовательский или сторонний import, чтобы пользователи могли знать, какие пакеты могут потребоваться для запуска скрипта. Вот пример скрипта, который используется для простого вывода заголовков столбцов электронной таблицы:

"""Программа вывода столбцов электронных таблиц

Этот скрипт позволяет пользователю выводить на консоль
все столбцы электронной таблицы. Предполагается, что
расположение столбцов определяется в первой строке
электронной таблицы.

Этот инструмент поддерживает файлы значений,
разделенные запятыми (.csv), а также файлы Excel (.xls, .xlsx).

Для этого скрипта требуется, чтобы `pandas` был установлен
в среде Python, в которой вы запускаете этот скрипт.

Этот файл также может быть импортирован в виде модуля
и содержит следующие функции:

    * get_spreadsheet_cols - возвращает заголовки столбцов файла
    * main - главная функция скрипта
"""

import argparse

import pandas as pd


def get_spreadsheet_cols(file_loc, print_cols=False):
    """Получает и печатает столбцы заголовка электронной таблицы

    Parameters
    ----------
    file_loc : str
        Расположение файла электронной таблицы
    print_cols : bool, optional
        Флаг, используемый для вывода столбцов
        на консоль (по умолчанию используется False)

    Returns
    -------
    list
        список строк, которые являются столбцами заголовка
    """

    file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        'input_file',
        type=str,
        help="Файл таблицы для вывода столбцов"
    )
    args = parser.parse_args()
    get_spreadsheet_cols(args.input_file, print_cols=True)


if __name__ == "__main__":
    main()

Форматы DocStrings

Возможно, вы заметили, что во всех примерах, приведенных в этом руководстве, используется специальное форматирование с общими элементами: Arguments (аргументы), Returns (возвращаемые значения) и Attributes (атрибуты). Существуют специальные форматы DocStrings, которые можно использовать, чтобы помочь анализаторам DocStrings и пользователям использовать привычный формат. В примерах, приведенных в этом руководстве, используются DocStrings в стиле NumPy/SciPy. Ниже приведены некоторые из наиболее распространенных форматов:

Выбор формата DocStrings зависит от вас, но вы должны придерживаться одного и того же формата для всего документа/проекта. Ниже приведены примеры каждого типа, чтобы дать вам представление о том, как выглядит каждый формат документации.

Пример Google DocStrings

"""Получает и печатает столбцы заголовка
электронной таблицы

Args:
    file_loc (str): Расположение файла электронной таблицы
    print_cols (bool): Флаг, используемый для вывода столбцов
        на консоль (по умолчанию False)

Returns:
    list: список строк, содержащий столбцы заголовка
"""

Пример reStructuredText

"""Получает и печатает столбцы заголовка
электронной таблицы

:param file_loc: Расположение файла электронной таблицы
:type file_loc: str
:param print_cols: Флаг, используемый для вывода столбцов
    на консоль (по умолчанию False)
:type print_cols: bool
:returns: список строк, содержащий столбцы заголовка
:rtype: list
"""

NumPy/SciPy

"""Получает и печатает столбцы заголовка
электронной таблицы

Parameters
----------
file_loc : str
    Расположение файла электронной таблицы
print_cols : bool, optional
    Флаг, используемый для вывода столбцов
    на консоль (по умолчанию False)

Returns
-------
list
    список строк, содержащий столбцы заголовка
"""

Пример Epytext

"""Получает и печатает столбцы заголовка
электронной таблицы

@type file_loc: str
@param file_loc: Расположение файла электронной таблицы
@type print_cols: bool
@param print_cols: Флаг, используемый для вывода столбцов
    на консоль (по умолчанию False)
@rtype: list
@returns: список строк, содержащий столбцы заголовка
"""

Документирование Ваших проектов на Python

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

project_root/
│
├── project/  # Исходный код проекта
├── docs/
├── README
├── HOW_TO_CONTRIBUTE
├── CODE_OF_CONDUCT
├── examples.py

Проекты в целом можно разделить на три основных типа: Private (личные), Shared (совместные) и Public/Open Source (публичные, с открытым исходным кодом)

Личные проекты

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

1. Readme: краткое описание проекта и его цели. Укажите особые требования к установке или эксплуатации проекта.
2. examples.py : файл скрипта на Python, который содержит простые примеры использования проекта.

Помните, что, несмотря на то, что частные проекты предназначены лично для вас, вы также считаетесь пользователем. Подумайте обо всем, что может вас смутить в будущем, и обязательно укажите это в комментариях, в строках документации или в readme.

Совместные проекты (Shared)

Совместные проекты - это проекты, в которых вы сотрудничаете с несколькими другими людьми в разработке и/или использовании проекта. “Заказчиком” или пользователем проекта по-прежнему остаетесь вы сами и те немногие, кто также использует проект.

Документация должна быть немного более строгой, чем это необходимо для частного проекта, в основном для того, чтобы помочь привлечь к проекту новых участников или предупредить участников/ пользователей о новых изменениях в проекте. Некоторые из рекомендуемых частей, которые следует добавить в проект, следующие:

1. Readme: краткое описание проекта и его цели. Укажите любые особые требования к установке или эксплуатации проекта. Кроме того, добавьте все существенные изменения, внесенные по сравнению с предыдущей версией.
2. examples.py : файл скрипта на Python, который содержит простые примеры использования проектов.
3. Как внести свой вклад (HOW_TO_CONTRIBUTE): Это должно включать в себя информацию о том, как новые участники проекта могут начать вносить свой вклад.

Публичные проекты

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

1. Readme: Краткое описание проекта и его цели. Укажите любые особые требования к установке или эксплуатации проектов. Кроме того, добавьте любые существенные изменения, внесенные с момента выхода предыдущей версии. Наконец, добавьте ссылки на дополнительную документацию, сообщения об ошибках и любую другую важную информацию о проекте.
2. Как внести свой вклад: Это должно включать в себя информацию о том, как новые участники могут помочь проекту. Это включает разработку новых функций, устранение известных проблем, добавление документации, новых тестов или отчетов о проблемах.
3. Кодекс поведения (CODE_OF_CONDUCT): определяет, как другие участники должны относиться друг к другу при разработке или использовании вашего программного обеспечения. Здесь также указано, что произойдет, если этот код будет нарушен. Если вы используете Github, можно создать шаблон Кодекса поведения с рекомендуемой формулировкой. Особенно для проектов с открытым исходным кодом, подумайте о том, чтобы добавить это.
4. Лицензия: Текстовый файл, описывающий лицензию, используемую в вашем проекте. Рассмотрите возможность добавления этого файла, особенно для проектов с открытым исходным кодом.
5. docs: Папка, содержащая дополнительную документацию. В следующем разделе более подробно описано, что должно быть включено и как организовать содержимое этой папки.

Четыре основных раздела папки docs

Даниэле Прочида выступил с замечательным докладом на PyCon 2017 и последующей публикацией в блоге о документировании проектов на Python. Он упоминает, что все проекты должны состоять из следующих четырех основных разделов, которые помогут вам сфокусировать вашу работу:

1. Учебные пособия: уроки, которые помогут читателю выполнить ряд шагов по завершению проекта (или важной задачи). Ориентированы на обучение пользователя.
2. Практические руководства: Руководства, которые знакомят читателя с шагами, необходимыми для решения общей проблемы (проблемно-ориентированные рецепты).
3. Ссылки: Пояснения, которые проясняют и освещают определенную тему. Ориентированы на понимание.
4. Пояснения: Технические описания устройства и способов его эксплуатации (ключевые классы, функции, API и т.д.). В пример энциклопедическая статья.

В следующей таблице показано, как все эти разделы соотносятся друг с другом, а также их общее назначение:

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

Инструменты и ресурсы для документирования

Документирование вашего кода, особенно в крупных проектах, может быть сложной задачей. К счастью, есть несколько инструментов и ссылок, которые помогут вам начать работу:

С Чего Мне Начать?

Документация по проектам имеет простую последовательность выполнения:

1. Никакой документации
2. Некоторая документация
3. Полная документация
4. Хорошая документация
5. Отличная документация

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

В конце концов, не расстраивайтесь и не перегружайтесь объемом работы, необходимой для документирования кода. Как только вы начнете документировать свой код, вам станет легче продолжать.