The Most Important Code Isn't Code

http://zachholman.com/posts/documentation/

Documentation is the single most important change I’ve made to my coding stylein the last year.

Documentation is Personal

I’m not talking about injecting a few comments in front of confusing lines hereand there. I’m talking about taking a firm, consistent view at how you documentyour methods, your classes, and your projects, and then sticking to thatmentality. Documentation is mostly described as a way to communicate yourthoughts to other developers, but honestly, other developers can eat it.Documentation is the best way to communicate your thoughts toyourself.

Documentation is Clarity

If you don’t have an absolute clarity in the code you’re pushing, it rears itshead by way of bugs, confused coworkers, and slow code. Straightforwarddocumentation has given me that clarity.

I typically hate process. From TDD to BDD to Agile to everything else, itusually feels too cumbersome for me to stick with it. But two mentalities havereally impacted me:TomDoc and Readme Driven Development. Bothwere designed by Tom Preston-Werner. Both have documentation at theircore. Though they’re both obviously helpful for other developers who look atyour code, I’ve found them to be extremely helpful tome as I code.

Writing the README first means you think about the end-product first. Thatseems somewhat silly — I mean, I’m writing this library, don’t I already knowwhat’s coming next? But that’s usually not the case. More often than not Iwould jump straight into the challenging part of the project since I thoughtthat’s where the substantive part is. It’s not.The end result is always thesubstantive part of your project. Forcing myself first to consider the API,the interface, and the end result led to a clarity that inspired less code anda more impactful project.

I feel similarly about TomDoc. TomDoc is a mentality that places emphasis onclear, straightforward, explicit documentation. Here’s a simple example takenfrom the TomDoc spec:

# Duplicate some text an abitrary number of times.
#
# text  - The String to be duplicated.
# count - The Integer number of times to duplicate the text.
#
# Examples
#
#   multiplex('Tom', 4)
#   # => 'TomTomTomTom'
#
# Returns the duplicated String.
def multiplex(text, count)
  text * count
end

You describe your method arguments, and you detail your response. Every time.It can sometimes feel repetitive, but that repetitive feeling is one of those Istrongly welcome. It improves the clarity of my code. I get more done in lesslines. The documentation style itself is clear, too. I write this blog in JohnGruber’s Markdown because Markdown looks and feels like plaintext. Iuse Tom Preston-Werner’s TomDoc becauseTomDoc looks and feels likeplaintext. There’s very little interface to learn between writing it downand rendering it in your head.

Documentation is Testable

Documenting code in TomDoc has lead me to two big testing personal“breakthroughs”, if you will. Since you’re required to detail every methodargument, you’re forced from the beginning to consider how those inputs end upimpacting that method. You think about the edge cases explicitly. Convenientlyenough, those edge cases almost always translate into real test cases. I don’tconsistently TomDoc first or write my test first, but they almost always happensimultaneously, since they effectively work in tandem. One helps you write theother.

My second “breakthrough” is realizing that if some method is hard to document,it’s too big. Ruby in particular has been harping for years that you wantshort, focused methods. I know that. Everyone’s known that since their thirdweek using Ruby. But even if you’ve been writing Ruby for years, you can prettyquickly fall into the classic “oh I’ll just handle this here too” mentality.Once I do that, I end up trying to document more method arguments, morepossible method outputs, and it’s just more work. Once that happens, it’s anobvious reminder that I messed up this method and should break it into two orthree other methods. That means smaller, more resilient and easier-to-testmethods, which directly translate into less brittle code.

Documentation is Diffable

Over the last year or so, we’ve been adding more and more TomDoc to code thatwe push here at GitHub. It’s not high priority or anything, but if you refactoror touch old code, it’s nice to add documentation for it.

We’re now at 30-plus employees, and there’s a lot of code flying around. Whensomeone pushes to a GitHub repository,Hubot, our trustyCampfire bot, jumps in and posts a Compare View of the changes:

This hook is important. It’s how everyone at GitHub can see how GitHub ischanging incrementally. The commit messages in Git are helpful to see what’shappening, but sometimes the commit message and (particularly!) the codedoesn’t really give you a good idea of what or why something is changing.

Seeing the changes in a huge block of documentation in the Compare View onGitHub ends up being much easier to parse. You can see which arguments gotremoved, which new edge case is defended against, what changes are made in thepublic API. It’s another tool in your belt to help communicate code changes toeveryone else.

Documentation is Marketing

I love the idea of documentation as marketing. A good README gets people tojump into your project much, much quicker. Heavily-documented code means otherscan read your project much, much quicker. Heavily-documented code means otherswill tend to break your tests less.

This extends to project websites and documentation as well. In fact, I lovethis documentation-as-marketing concept so much thatI wrote aboutit. Even though I get a lot out of my documentation, thatdoesn’t mean that it can’t serve as a promotional vehicle for my project,either.

Documentation helps you in the bedroom

Well, I’m still trying to test the validity of that. But documenting your codeis cool as hell. More importantly, it makes me feel more confident about my owncode. You don’t need to go full-bore Readme Driven Development, you don’t needto use TomDoc, you don’t need to follow any particular process. But improvingyour documentation skillswill make you a better developer.