Names and Signatures are not full documentation
// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
// bad
/// Returns a future that resolves when operation completes.
fn sync_to_server() -> Future<Bool>;
// good
/// Sends local edits to the server, overwriting concurrent edits
/// if any happened.
fn sync_to_server() -> Future<Bool>;
// bad
/// Returns an error if sending the email fails.
fn send(&self, email: Email) -> Result<(), Error>;
// good
/// Queues the email for background delivery and returns immediately.
///
/// Returns an error immediately if the email is malformed.
fn send(&self, email: Email) -> Result<(), Error>;-
Motivation: API designers can over-commit to the idea that a function name and signature is enough documentation.
-
Again, names and types are part of the documentation. They are not always the full story!
-
Consider the behavior of functions that are not covered by the name, parameter names, or signature of that function.
-
It is not obvious that
sync_to_server()could overwrite something (leading to a data loss), so document that. -
In the email example, it is not obvious that the function can return success and still fail to deliver the email.
-
-
Use comments to disambiguate. Nuanced behaviors, behaviors that users of an API could trip up on, should be documented.