Document your damn code.

Me, recently.

This gif is more-or-less the last 72 hours of my life. Or at least, a documentary of the internal screaming resulting from dealing with several (read: a week on Wednesday) days of dealing with undocumented legacy code.

I think these two terms go hand in hand, and you all know where I’m going here. This is going to be my rant of probably not-so-epic proportions of why you should document your code. At times, the arguments will be bad. At other times, hopefully they get my point across.


The New Dev — Some Backstory Here

Hi. Let me get one thing straight: I fucking love my job. This is, hands down, the best job I’ve ever had.

Yes, I started a month ago.

However, this job also happens to basically be my dream job. Not only do I get to work in web, but I also get to do low-level coding — I was the kid in school who actually enjoyed their assembly class, and actually really missed it after I dropped out.

It doesn’t matter the languages you’re in. If you’re new, things might not make sense. The dev before me wrote reams of fantastic documentation on our processes. The problem is — a change went out last week that basically meant working night/day on code I barely knew, with processes I’ve only sort-of felt comfortable with.

It’d be a living nightmare if I didn’t absolutely enjoy every god damn moment of it.


The Arguments

I’ve worked in a lot of places, and I’ve attended two different universities. So let me start first with my rant about people at universities.

The professors always required code documentation. The university I’ll be graduating from taught C++ when I first started (and only recently — in the last year — transitioned to Java). My code documentation looked something like this:

// — — — — — — — — — — — — — — — — — — — — — — — — — — — — 
// Description: Validates the read data and puts it into
// arrays
// Input params: rentalUnits — rental array of units
// read from file
// MAX_RENTALS — max amount of rentals
// amntRentals — the count of rentals
// Output Params: rentalUnits, amntRentals
//
// Return: bool
// — — — — — — — — — — — — — — — — — — — — — — — — — — — —

The code itself even had a few here and there, but nothing too prolific. Your basic main():

bool useExistingFile(){ 
bool useExisting = false;
char userInput;
   while(toupper(userInput) != ‘Y’ && toupper(userInput) != ’N’) { 
cout << “Load existing data from a file (Y/N)? “;
cin >> userInput;
// bad input, reprompt
if(toupper(userInput) != ‘Y’ && toupper(userInput) != ’N’) {
cout << “Please enter Y for Yes or N for No.” << endl; }
else {
if(toupper(userInput) == ‘Y’) {
useExisting = true;
}
}
}
return useExisting;
}

It’s not the prettiest function, but it gets the point across. Reads the user input, if its bad input, then it reprompts. Once it gets an answer, it returns a true or a false.

Except, notice it has 1 inline comment. And I run into so much code that won’t even do this (I mean, admittedly — I don’t comment all of my code). Because it doesn’t need that much. The documentation above tells you pretty much all that you really need to know.

Yet so many university students have been marked down because of their blunt resistance to writing simple, documentation comments. Because they’re too “time consuming” (frankly: text macros are your friend. This kind of shit takes you at most a few seconds per function — and if you write them before you write the function, your code ends up better, anyhow.)

This goes on into the workplace.

But what if the code changes and you don’t update the comments? Then it’s more confusing!

So what you’re saying right now is that you’d rather just be lazy? Does it take you this long to type a sentence? Have you stopped to think you aren’t the only developer working on this project?

If you don’t understand this code, you can just ask.

Chances are, the original author won’t be there to ask. I’ve run into that far more often than not.

I’ll also add that I’ve found that this kind of attitude ends up being a bit egotistical, and falls into:

Code should be self-documenting. There’s no reason for comments!

We all know what self-documenting code is. Heck, the function I provided up there is pretty self-documenting itself. But doesn’t this contradict your first argument as well?

If I have a variable named a certain way, or a function, and then I change them to do something “else” — I also need to update my unit tests, and if we’re relying on this code to be self-documenting… Then I also need to update all of their names. So doesn’t it contradict what you’re saying about not having comments (because they’ll be confusing) if I don’t also take these steps with my code? Shouldn’t updating comments if I’m changing the entire damn thing?

Let me finish my point

First: notice my title is document. Not simply comment. However, comments are — in my least humble opinion — the most effective form of code documentation. I’m not going to read a confluence page while trying to fix a bug or add a feature to an existing code base.

I don’t believe you should write as many comments in your code as I do when I’m having a hard time figuring out how the hell to fix something:

(for the record, this was written with a bit of alcohol several hours after the due date).

But the point is, something like this gets the point across, is readable, and in a few years after I’ve returned from hiding in Fiji after revealing to Medium that I once forgot how to write a basic binary search at two in the morning, I’ll still likely be able to figure out what’s going on (note: I actually did add a few comments to this, as I realized that out of context many of its variables don’t make sense):

And yes, I’m aware I can use cleaning for that function. This isn’t a review of coding skills — this is a reminder that comments are very good to have.

So stop making excuses for “too many” comments. You aren’t writing comments for your compiler — you’re writing them for the next extremely stressed developer that’ll be taking over the project. And sometimes, that developer will be you.

So treat yo’self: write comments! Because there’s no actual good excuse to not have them.