There’s probably a morality tale somewhere in here.

A BASH script wasn’t working in the VM I was testing it on, and I thought sure the tutorial I was using was wrong. (I was getting a little bit irritated, in fact.)

I wrote out a question for Stack Exchange, but decided to sleep on it before posting it.

I looked at it the next day and I immediately saw what I did wrong. It was kind of obvious, actually. Stack Exchange would have been a waste of other people’s time.

I’m not exactly sure what the lesson here is, but it does remind me of something that I used to say when I was in grad school: The three most important things in math are patience, coffee, and naps. Patience because you’ll be able to understand something better if you take it slowly. Coffee because, well, coffee. Finally, naps because sometimes, as one of my teachers used to say, your brain can get full, and you just need to take a step back and take a break before coming at it with a fresh mind. I think this applies to programming as well as it does mathematics.

<@Logan> I spent a minute looking at my own code by accident.
<@Logan> I was thinking "What the hell is this guy doing?"

It seems that the conventional wisdom of the day is that documentation for code should be minimal, if it exists at all. This may be related to Agile methods, but that seems to be in some dispute. (I have a number of criticisms of Agile in general, but I’ll leave that for another time.) What I hear most often is that “Function names should be clear enough that you know what they do.”

I respectfully disagree. The reason why is because it requires that everybody on the team think in exactly the same way. Not everybody agrees that functions shouldn’t have side effects. Not everybody encapsulates code into functions. Not everybody adheres to MVC design patterns. Unfortunately, It’s not going to do me much good to scream at my team that they use the same standards that I do. Even if that worked, not everyone is going to interpret those standards and implement them in exactly the same way.

Most of the scripts that I come across are just giant procedures, usually between 400 to 3000 lines long. (Who knows why they did it that way– Probably wrote it in a hurry and it snowballed after a lot of tweaking.) Then someone asks me to add a feature, and I have no idea where to even begin.

Someone may reply, “This isn’t a lack of documentation problem, but a code clarity problem.” This is partly true. However, the problem is that not everyone has the same idea of what constitutes clearly-written code. Many people think those giant procedures are easier to understand.

What eventually ends up happening is someone has to explain those procedures. So, we still end up having documentation, but now it’s word-of-mouth instead of written word. Then begins a new nightmare. (The telephone game in a business setting is not fun.)

Since not everyone is an Uncle Bob clone, it’s better long-term practice to go ahead and encourage documentation. Standardizing a team’s practice is also great; don’t get me wrong. However, not everybody is going to interpret standards the same way and implement them consistently. The idea of “Write what this script does” is much easier to put into practice. It may take a little longer at first, but it really reduces the amount of confusion later on. (And use DocBlocks– They’re really convenient to write and useful to read.)