Имена и сигнатуры не являются полной документацией
// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
// плохо
/// Возвращает фьючерс, который завершается при завершении операции.
fn sync_to_server() -> Future<Bool>;
// хорошо
/// Отправляет локальные правки на сервер, перезаписывая параллельные правки,
/// если они были.
fn sync_to_server() -> Future<Bool>;
// плохо
/// Возвращает ошибку, если отправка письма не удалась.
fn send(&self, email: Email) -> Result<(), Error>;
// хорошо
/// Ставит письмо в очередь на фоновую доставку и сразу возвращает управление.
///
/// Сразу возвращает ошибку, если письмо составлено неправильно.
fn send(&self, email: Email) -> Result<(), Error>;-
Мотивация: авторы API могут слишком полагаться на идею, что имени функции и сигнатуры достаточно как документации.
-
Ещё раз: имена и типы являются частью документации. Но они не всегда дают полную картину!
-
Учитывайте поведение функций, которое не отражено в имени функции, именах параметров или её сигнатуре.
-
Неочевидно, что
sync_to_server()может что-то перезаписать (что приведёт к потере данных), поэтому это нужно задокументировать. -
В примере с письмом неочевидно, что функция может вернуть успех и всё равно не доставить письмо.
-
-
Используйте комментарии для устранения неоднозначности. Тонкие моменты поведения, на которых пользователи API могут споткнуться, должны быть задокументированы.