friflex_flutter_starter/tools/rfc/RFC-documentation.md

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

Документация

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

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

Шаблоны и примеры документации объектов

Документация классов:

    /// {@template new_class}
    /// Класс для реализации {описание назначения и реализуемого функционала в классе}.
    /// {@endtemplate}
    class NewClass {}

Пример:

    /// {@template app_button}
    /// Класс для реализации кастомизированной кнопки.
    /// {@endtemplate}
    class AppButton {}

Документация конструкторов и фабрик:

Если конструктор один, то достаточно указать {@macro new_class}. {@macro new_class} дублирует на конструктор указанную в рамках описания класса документацию, поэтому описание класса должно в таком случае включать все передаваемые в конструктор параметры Если конструкторов несколько, описания должны отражать их отличия друг от друга. Фабрики описываются по такому же принципу.

    ///{@macro new_class}
    const NewClass();

    /// Создает {описание создаваемого фабрикой объекта}.
    /// Принимает:
    /// - [json] - {описание параметра}
    factory NewClass.fromJson(Map<String, dynamic> json)

Документация полей классов:

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

    /// Возраст пользователя.
    final int age;

    /// Индикатор совершеннолетия пользователя. Принимает значение true, когда [age] больше 18 лет.
    final bool isAdult;

Документация геттеров/сеттеров:

    /// Получения доступа к {описание данных, которые получает геттер}
    int get newGetter => ...

    /// Установка значения для {описание работы сеттера}
    set newSetter (int setterValue) => ...

Документация методов:

Методы должны описывать их основное назначение. Если метод сложный, требуется указывать дополнительное описание его работы ниже через пропущенную строку. Если метод принимает какие-либо параметры, каждый параметр должен быть описан по отдельности списком с прямой ссылкой. Если метод возвращает какие-либо значения, они должны быть описаны. Желательно указать, что вернет метод в случае возникновения ошибки.

    /// Метод для {описание назначения метода}.
    /// {описание особенностей работы метода}.
    /// Принимает:
    /// - [param] - {описание назначения параметра}.
    void newMethod({required String param}) {
        ...
    }

Пример:

    /// Метод для расчета температуры.
    /// Принимает:
    /// - [grad] - параметр необходим для расчета температуры.
    /// Возвращает:
    /// - температуру в градусах.
    /// При ошибке расчета возвращается null.
    int? calcTemperature({required int grad}){
        // Реализация
    }

Комментарии

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

• комментарии оформляются над описываемым участком кода с использованием '//';
• комментировать необходимо те участки кода, которые действительно нуждаются в дополнительном описании;
• комментарий не должен повторять легко читаемые участки кода

Например:

 if(flag != true)  // не нужно описывать как "Если значение не равно true...

Например:

 if(isAurora){
    // Так как Аврора не может открывать WebView, 
    // то  заменяем на открытие внешнего браузера
 }

TODO

Основные правила создания TODO в проекте:

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