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.