Beyond Comments: Living Documentation with Executable Examples

Comments are a cornerstone of software development. They explain why code does what it does, providing context and reasoning that isn’t always evident from the code itself. However, comments can become outdated, inaccurate, or simply ignored. This leads to a disconnect between the documentation and the actual codebase, a problem we can address with living documentation.

What is Living Documentation?

Living documentation is documentation that is always up-to-date because it is directly linked to and verified by the code itself. This eliminates the risk of documentation drifting out of sync with the implementation. Executable examples are a key component of this approach.

The Problem with Traditional Documentation

• Outdated: Comments and external documentation can become stale as the code evolves.
• Difficult to Maintain: Keeping documentation synchronized requires significant effort and discipline.
• Ambiguous: Natural language explanations can be open to interpretation and misunderstanding.
• Not Verifiable: There’s no guarantee that the documentation accurately reflects the code’s behavior.

Executable Examples: A Solution

Executable examples are code snippets, often unit tests or integration tests, that demonstrate how to use a particular function, class, or module. They serve as both documentation and verification, ensuring the examples remain accurate as the code changes.

Benefits of Executable Examples

• Always Up-to-Date: Executable examples are part of the testing process. If they fail, it indicates a change in behavior that needs to be addressed in both the code and the documentation.
• Clear and Concise: Examples are written in code, leaving less room for ambiguity compared to natural language descriptions.
• Testable: The examples are themselves tests, providing confidence in the code’s functionality and the documentation’s accuracy.
• Discoverable: Well-written examples can serve as a starting point for developers learning how to use the code.

How to Implement Executable Examples

There are several approaches to incorporating executable examples into your workflow:

• Docstrings with Examples: Many languages allow you to embed executable examples within docstrings.

  def add(x, y):
      """Adds two numbers together.
  >>> add(2, 3)
  5
  >>> add(-1, 1)
  0
  """
  return x + y
  
  
  Tools like doctest (Python) can then execute these examples and verify their correctness.
  

• Unit Tests as Examples: Writing comprehensive unit tests that demonstrate various usage scenarios.

  import org.junit.jupiter.api.Test;
  import static org.junit.jupiter.api.Assertions.assertEquals;
  
  class CalculatorTest {
  @Test
  void testAddPositiveNumbers() {
      Calculator calculator = new Calculator();
      assertEquals(5, calculator.add(2, 3));
  }
  
  }
  
  
  The tests clearly illustrate how to use the add method.
  

• Storybook (for UI components): Storybook allows you to create isolated environments for UI components with various examples of their usage.

• Tools for Combining Tests and Documentation: Some tools (like Sphinx with extensions) can automatically generate documentation from test results and code.

Best Practices for Writing Effective Executable Examples

• Keep Examples Simple and Focused: Each example should demonstrate a single concept or use case.
• Use Clear and Concise Code: Avoid unnecessary complexity in the examples.
• Provide Context: Include brief explanations of what the example demonstrates.
• Maintain Consistency: Use a consistent style for all examples.
• Automate Execution: Integrate the examples into your build and test process.

Conclusion

Moving beyond traditional comments and embracing living documentation with executable examples offers a powerful way to keep your documentation accurate, relevant, and useful. By making your documentation an integral part of your testing process, you can significantly improve the quality of your code and the overall developer experience. This investment in living documentation will pay dividends in the long run by reducing errors, improving maintainability, and accelerating development.