mirror of
https://github.com/smmarty/friflex_flutter_starter.git
synced 2025-12-22 09:30:45 +00:00
131 lines
6.6 KiB
Markdown
131 lines
6.6 KiB
Markdown
# Ведение документации и комментариев
|
||
|
||
## Документация
|
||
|
||
### Основные правила ведения документации в проекте
|
||
|
||
- документация оформляется над описываемым объектом с использованием '///';
|
||
- документацией необходимо покрывать все классы, конструкторы, поля, геттеры, сеттеры, методы, фабрики, все кастомные объекты;
|
||
- документация должна:
|
||
- указывать на назначение объекта;
|
||
- содержать исчерпывающее описание объекта;
|
||
- быть краткой и емкой;
|
||
- быть понятной для любого разработчика.
|
||
|
||
## Шаблоны и примеры документации объектов
|
||
|
||
### Документация классов
|
||
|
||
```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 необходимо оставлять на тех участках кода, которые требуют дальнейшей доработки;
|
||
- если известно, в рамках какой задачи будет доработан помечаемый участок кода, ссылку на задаче необходимо оставить в скобках.
|