Skip to content

DOCUMENTATION_STYLE.md

Latest commit

 

History

History
71 lines (60 loc) · 2.1 KB

DOCUMENTATION_STYLE.md

File metadata and controls

71 lines (60 loc) · 2.1 KB

Style Guide

Comments

  • All comments must end with a period.
  • Use complete sentences.
  • Avoid stating the obvious.

Documentation Comments

  • Use /// for public APIs, // for internal code.
  • Write in third-person declarative voice: "Returns the value" not "Return the value".
  • Use present tense and active voice.

Structure

/// Parses the input string into an abstract syntax tree.
///
/// Returns an error if the input contains invalid syntax.
fn parse(input: &str) -> Result<Ast, ParseError> {
    // Convert the raw token into a parsed expression.
    let expr = self.parse_token(token)?;
}

Module Documentation

//! Parser for the Morel language.
//!
//! This module provides functionality for parsing Morel source code
//! into abstract syntax trees.

Error Messages

  • Use sentence case and end with a period.
  • Be specific and suggest solutions when possible.
return Err("Failed to parse expression: unexpected token 'let' at line 42."
    .into());

Commit Messages

  • Use imperative mood: "Add parser support".
  • Capitalize first letter, keep under 72 characters.

Code structure

  • Use 4 spaces for indentation.
  • Consolidate impl blocks for the same type within the same file.
  • Reduce uses of qualified names by adding imports; if duplicate names are used in the same file, consider adding aliases.