Archive: Month June (2012)

Inline documentation is a sore subject for a lot of developers. Many see it as wasteful; it easily becomes stale, it’s yet-another-thing to maintain, and if you can already read your language of choice, it doesn’t provide any real value.

Documentation is not for you; it’s for everyone else. (Well, it’s for you too, but the future you.)

Avoiding comments because your code is “readable and understandable” makes several assumptions about your audience, such as them having any working knowledge of the language you’re programming in.

Our jobs (specifically as leaders in open-source communities) are to grow the platforms we’re responsible for. By catering to only developers, we end up ruling out contributions from everyone that isn’t currently a developer at our levels. That’s sad for everyone.

The natural response is: if you need to add a comment to your code, you’re being too clever. This, again, makes assumptions about your contributing audience. Thing is, it’s not about adding comments to difficult-to-understand or poorly-written code, it’s about translating gibberish into plain English so a bigger audience can contribute.

Inline documentation is the nonce-check of the open-source universe; it promises what’s actually happening in gibberish-land matches the intention of that section of code. There are a million excuses not to document your code, but it all boils down to either:

1. Being selfish.
2. Being lazy.
3. Being in a hurry.
4. Not knowing any better.
5. Being so insanely good at reading everyone else’s code that documentation has never in any way helped you.

Rarely is #5 the case; that only leaves ignorance and carelessness, which are unacceptable if you respect and admire your colleagues, users, and the efforts of your communities and teams of developers.

So, please… document what the heck you’re trying to do.