Documentation - It Matters

So documentation... I've been stressing this out since forever that an app should have an accompanying documentation of some form. People don't care. They just write code like there was no tomorrow. So this week, I transitioned to another project and found myself dumbfounded... ROFL ZOMG WTF! A pile of code with ZERO DOCUMENTATION. Yep! Zip, zilch, zero, nada, NOTHING! And oh boy I ain't seen nothing yet. Preparing myself for a whole lot of hurt.

A little more background

The app was built on PHP5 but was meant to run on constrained hardware. That meant weird programming practices, low-level-ish code, complex build systems and the like. Almost analogous to writing JS in ES6, transpile to ES3, compress with Closure Compiler and run on NodeJS with hard memory limits on a server box no stronger than a dual-core Pentium.

Now let's make matters worse. The original developers are no longer present. The last of these developers were known weirdos. The commit messages are utter trash. Code comments are meaningless. The project structure is a mess. It's written in sigh OOP (I'll take my OOP frustrations elsewhere). Oh wait, did I mention it was written from scratch? Yep, no StackOverflow help (Well, there's me helping me. >:D). Nothing I can't handle, but (flips table).

Documentation - It's an act of kindness

queue elevator music]

Writing documentation, in one way or another, is a form of kindness to your fellow developers. It gives them indication that you care for the app and the other developers involved. It's also an act of kindness to yourself. Writing code yourself doesn't guarantee that you'll remember why you did it. Don't believe me? Try explaining why you did a commit 2 weeks ago just by looking at the code. I bet you can't even recognize real code from hacked code!

I know it's hard to love when you'll have to let go. But instead of saying nothing and be bitter to the next person they'll be with, provide your last few words of wisdom before you set them free. Who knows, they might come back to you. That's what documentation should be like.

Anyhoo, documentation comes in many forms. Here's a few of them that makes sense to developers:

Comments

Comment. Liberally. A good practice of writing comments is to write the why. Why is the code there? Why it it done that way? Writing the how is redundant. Reading the code will tell you how it was done. Only when the code is obscure should you reiterate in the comments how it was done. I usually do this on operations that deal with bitshifting and hex values.

Commit messages

They're mainly focused on why the code was included in the codebase. A good commit message must have a summary on the first line. It's like a tweet, but in 70-80 characters. Following that is a description of why the change was needed. Here I usually state if there was a bug, or a requirement. After that, I'd put in a high-level description of how it was implemented.

Readmes

It's the defacto instruction manual for your project. The nice thing about putting a readme file (and a few other files in a docs directory) is it's checked in and versioned with the code. That means you can roll back to a revision, and readily see its corresponding documentation. A readme should contain a minimum of a project description, project structure, how to setup, how to run, how to debug.

Why NOT offsite resources?

By off-site resources, I refer to documentation outside the repo. This includes wiki sites and notebook applications. The problem with these resources is that they're not in the project. They easily become out-of-sync with the current state of the product. I doubt you even have the time to go through a thousand notebook pages and determine which ones are still relevant. Worse is when a non-technical person is assigned to do this. Everything sounds relevant!

Conclusion

Spare time for documentation. The only thing that gets stressed out is your patience and your grammar skills. Other than that, it shouldn't take an hour to make. As for me and that PHP project, we'll meet again in the following days. This time, I have my keyboard and mouse ready to put some sense to it.