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

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

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

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

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

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

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

Пример:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

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

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

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

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

Например:

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

## TODO

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

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