Документирование смарт-контрактов (NatSpec)
Контракт без документации — это контракт, который невозможно безопасно проинтегрировать. Разработчик, который будет использовать ваш токен через полгода, не должен реконструировать логику из байткода и тестов. NatSpec — стандарт inline-документации для Solidity, который читается людьми, генерируется инструментами и отображается в MetaMask при подписании транзакций.
Что такое NatSpec и как он работает
NatSpec (Natural Language Specification) — это набор тегов в комментариях Solidity, которые компилятор включает в ABI и отдельный JSON-документ. Поддерживает два формата: однострочный (///) и блочный (/** */).
Основные теги:
-
@title— название контракта -
@notice— описание для конечного пользователя (отображается в MetaMask) -
@dev— технические детали для разработчика -
@param— описание параметра функции -
@return— описание возвращаемого значения -
@custom:tag— кастомные теги (аудит-заметки, security notices)
Пример правильно задокументированной функции:
/// @notice Переводит токены на указанный адрес
/// @dev Не работает с ERC-777 токенами из-за hook'ов; используй safeTransfer для неизвестных получателей
/// @param to Адрес получателя, не может быть address(0)
/// @param amount Количество токенов в минимальных единицах (wei)
/// @return success True если перевод прошёл успешно
function transfer(address to, uint256 amount) external returns (bool success);
Что генерируется из NatSpec
forge doc (Foundry) или solidity-docgen генерирует Markdown/HTML документацию из NatSpec-комментариев. Результат — структурированный API-референс с описанием каждого контракта, функции, события и ошибки.
Для публичных протоколов это критично: аудиторы работают быстрее с задокументированным кодом, интеграторы не задают вопросы в Discord, пользователи видят понятный текст в кошельке перед подписью.
@custom:security и @custom:oz-upgrades-unsafe-allow — специальные теги, которые читают инструменты (OpenZeppelin Upgrades проверяет помеченные unsafe паттерны). Не просто документация — машиночитаемые аннотации.
Что документируем
Обязательно: все public и external функции, все события (event), все кастомные ошибки (error), все state-changing операции. @notice — с позиции пользователя, @dev — с позиции интегратора.
Необязательно, но полезно: internal функции в библиотеках, сложные алгоритмы (AMM формулы, reward calculation), security-критичные предположения (@dev Assumes price oracle is not manipulable within single block).
Полная документация контракта среднего размера (500-1000 строк) — 1 рабочий день. Генерация и настройка docgen-пайплайна — ещё 2-4 часа.