Avoiding Redundancy

Names and type signatures communicate a lot of information, don’t repeat it in comments!

#![allow(unused)]
fn main() {
// Repeats name/type information. Can omit!
/// Parses an ipv4 from a str. Returns an option for failure modes.
fn parse_ip_addr_v4(input: &str) -> Option<IpAddrV4> { ... }

// Repeats information obvious from the field name. Can omit!
struct BusinessAsset {
  /// The customer id.
  let customer_id: u64,
}

// Mentions the type name first thing, don't do this!
/// `ServerSynchronizer` is an orchestrator that sends local edits [...]
struct ServerSynchronizer { ... }

// Better! Focuses on purpose.
/// Sends local edits [...]
struct ServerSynchronizer { ... }

// Mentions the function name first thing, don't do this!
/// `sync_to_server` sends local edits [...]
fn sync_to_server(...)

// Better! Focuses on function.
/// Sends local edits [...]
fn sync_to_server(...)
}
  • Motivation: Documentation that merely repeats name/signature information provides nothing new to the API user.

Additionally, signature information may change over time without the documentation being updated accordingly!

  • This is an understandable pattern to fall into!

    Naive approach to “always document your code,” follows this advice literally but does not follow the intent.

    Some tools might enforce documentation coverage, this kind of documentation is an easy fix.

  • Be aware of the purpose of different modes of documentation:

    • Library code will need to be documented in ways that understand the scope of what it is used for and the breadth of people who are trying to use it.

    • Application code has a more narrow purpose, it can afford to be more simple and direct.

  • The name of an item is part of the documentation of that item.

    Similarly, the signature of a function is part of the documentation of that function.

    Therefore: Some aspects of the item are already covered when you start writing doc comments!

    Do not repeat information for the sake of an itemized list.

  • Many areas of the standard library have minimal documentation because the name and types do give enough information.

    Rule of Thumb: What information is missing from a user’s perspective? Other than name, signature, and irrelevant details of the implementation.

  • Don’t explain the basics of Rust or the standard library. Assume the reader of doc comments has an intermediate understanding of the language itself. Focus on documenting your API.

    For example, if your function returns Result, you don’t need to explain how Result or the question mark operators work.

  • If there is a complex topic involved with the functions and types you’re documenting, signpost to a “source of truth” if one exists such as an internal document, a paper, a blog post etc.

  • Collaborate with Students: Go through the methods in the slide and discuss what might be relevant to an API user.

More to Explore

  • The #![warn(missing_docs)] lint can be helpful for enforcing the existence of doc comments, but puts a large burden on developers that could lead to leaning onto these patterns of writing low-quality comments.

    This kind of lint should only be enabled if the people maintaining a project can afford to keep up with its demands, and usually only for library-style crates rather than application code.