Documentation Tradeoffs and Why Commit Messages are Worth Spending Time On

Documentation Tradeoffs and Why Commit Messages are Worth Spending TimeĀ On

We've all thought "what is this thing supposed to do?" or "why was this done that way" moment when looking through codebases and unless there's documentation or you can find the author, the answer is often hard to find. There are many options to document code from comments to internal wikis, so I'll discuss a heuristic for evaluating the options based on the accessibility (how far away is the answer?) and accuracy (how likely is it that what I'm reading is out of date?) to build a case that the git commit message is likely where you should spend your energy documenting. I'll share my workflow and how to leverage tools tools like git-blame to get the most out of your git history.

Cf9418e41c844d90cbd29e9061f7ba9c?s=128

Gregg Rothmeier

November 14, 2018
Tweet