(Self-)Documenting Code

Low friction doc creation & maintenance

Stijn Dejongh | 2024-10-24

Abstract

The goal of software documentation is to be useful: providing clarity and support to developers maintaining and expanding the codebase. Yet, the time spent on external tools to write and update documentation often feels like a distraction from actual coding. In this lightning talk, we’ll explore a more streamlined approach: using tools and techniques that allow developers to stay in the codebase while generating useful documentation artifacts.

From naming conventions, comments, and tests to diagrams-as-code and static site generators, we’ll dive into practical strategies to reduce friction and make documentation as low-effort as possible. The aim isn’t to eliminate documentation tasks, but to integrate them smoothly into the development workflow. Providing actionable tips, this session is aimed at developers looking to maintain useful documentation without breaking their flow.

Why (don’t we) document code?

The docs are a lie

Source Code never lies

We like good documentation

  • helps us understand the code
  • helps us implement new features
  • helps us avoid mistakes
  • saves us mental energy

We hate writing it

  • Working Software over Comprehensive Documentation
  • Low immediate value
  • Maintenance burden
  • Tools are often cumbersome

Goal: Reducing friction!

  • Documentation should be a byproduct of the process
  • Good documentation should be: UWMA

Useful

  • The code
  • The project
  • The organization
  • Past decisions
  • Common tricks and traps

Well-Maintained

  • Aligned with reality
  • Updated frequently
  • Whole team effort

Accessible

  • Easy to find
  • Clear and concise
  • Actionable
  • Searchable

Writing Documentation

Most organizations have their own standards for design documentation. These standards can range from “You must use confluence” to “Just write it down on a napkin and take a picture of it”.

What to document?

Intent

  • Why are we doing this?
  • Who cares?
  • What are we trying to achieve?

When in doubt: follow the money!

Why? Who? What?

Structure

  • High-level overview of placement in organization
  • Key interaction with other systems
  • Module-level overview
  • Technical Dependencies

Decisions

  • What?
  • When?
  • Why?
  • Why not X ?

Issues and Improvements

  • Known bugs
  • Code quality metrics
  • Change rate
  • Code smells and Security issues

Usage and Examples

  • How to use (part of) the code
  • Usage metrics

Recap

from: traceable decisions

Self-documenting code?

(Self-)Documenting Code

Repository Structure

  • Create a README.md
  • Describe the project, and its purpose
  • Describe the directory structure
  • Actually use JavaDoc!

readme example

JavaDoc, but not as you know it

Test Cases

  • Write test names as specifications
  • Avoid weasel words
  • 4xA Test Structure (Arrange, Assume , Act, Assert)
  • Dogfooding
  • Test adherence to your conventions!

Annotations and Comments

  • Describe the intent
  • Create custom annotations!

Annotations, the easy way

Code Change Rate

  • git knows all
  • git remembers all
git log --format=format: --name-only \\
  | egrep -v '^$' \\
  | sort \\
  | uniq -c \\
  | sort -rh

Code Change rate, lazy style

Low-friction tools

~
Keep your friends close, and your documentation even closer!
~

Plain Text all the way!

  • txt files, markDown, xml, json,plantUML, code,…
  • Plain text is easy to search, version, and diff
  • Plain text is easy to convert

Make it shine

  • Static Site Generators
  • JavaDoc + CSS
  • PlantUML

your IDE and pipelines can help

  • Script it once
  • Run it forever
  • You have a build pipeline and IDE anyway
  • Use it!

Thank you!

References

Source code used:

Brought to you by

  • Me, Stijn
  • MarkDown
  • reveal.js + HuGo

This presentation: Easter egg!