<@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.)