Немного о комментариях к коду

Я хочу еще раз поднять тему комментирования кода в процессе разработки и для проведения аудита.

В Solidity вы можете использовать специальные теги для пометки своего кода, вот их обозначения:

@title - заголовок
@author - автор кода
@notice -заметка о коде
@dev - пометка от разработчика
@param - описание параметров функции
@return - описание возвращаемой переменной

Как их использовать?

Например у нас есть простая функция:

functions example(uint256 amount, address receiver) external returs (uint128) {}

Ее описание может быть таким:

/*
*
* @title - кто написал эту функцию (разработчик);
* @title - что она должна делать?
* @notice - более детальное описание функции (можно на нескольких строках);
* @dev - пометка для других разработчиков;
* @param - amount отвечает за это...
* @param - receiver отвечает за это...
* @return - uint128 должна вернуть это...
*
*/

Такое описание должно быть практически для каждой функции в контракте. Для импортов и наследований достаточно оставлять @notice.

Для проведения аудита крайне рекомендую скачать приложение для VS Code - Inline Bookmarks от tintinweb, которое позволяет делать теговые заметки:

/*
*
* @audit - общие заметки по аудиту;
* @audit-info - дополнительная информация;
* @audit-issue - найденная уязвимость или проблема;
* @audit-ok - проверено и все ок;
*
*/

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

Ставьте комментарии и теги.

#natspec #comments