-
Notifications
You must be signed in to change notification settings - Fork 0
What is it About Documentation?
I mean, could someone please explain, why do so many people freak out when asked to document their code?
OK, yes, this is one of those personal rants. So sue me.
I want to stress that the focus of my comments (OK, rant) concerns coding for use in an enterprise environment; what the lone sysadmin does in the privacy of their own personal hobby servers is not my concern.
If you look at my code, pretty much everything has a somewhat-standard documentation header. It says a few words about what the tool does, gives requirements, usually has some design notes about limits or corner-cases or weirdness I encountered, mentions any glaring deficiencies I might know about but haven't yet addressed, lists other things I might need to do in the code, and contains a change log.
Really, it's not that hard to do; you don't have to write War and Peace.
Give 100 programmers a coding problem, and you'll get 128 different programs. There's always a perfectly valid solution that is different from whatever you wrote. Consider this (admittedly simple) example in modern BASH:
export MY_STRING='This is a test'
echo ${MY_STRING} | awk '{ print substr($0,1,length-2) }'
echo ${MY_STRING:0:(-2)}
The output from both echo statements is This is a te
Two different methods, exact same output. My point is not that one method is "wrong", or that the other method is "better". My point is that not everyone thinks the same way. Code that is blindingly obvious to me may be confusingly obscure to someone else, and vice-versa.
Well-written comments don't explain what your code does - they explain why it works the way it does. They reveal your design in human terms.
The code is for the computer, the comments are for the human who must maintain your code.
Plain language is fine; no one expects comments in iambic pentameter.
Most of my tools have a Help screen; it gets displayed when the tool is invoked with a -h parameter. I usually take the time make it look similar to a man page, and make it readable using some basic formatting, screen colors and highlighting - again, it's for my fellow humans and, really, not that hard (hint: I use a standard template).
A few years ago, I worked with a guy who thought himself so clever for coming up with:
I'll put the text of my 'Help' screen in a block of comments, and I'll make each line start with '# HELP' so I can grep my script and get those lines and use awk to chop off the leading text.
He was more about the letter than the spirit of the idea. Sure, it works (kinda). No real way to enhance the readability or control formatting; just a plain text dump but there'd (probably) never be a mistaken RegEx match.
The issue? He forgot it wasn't about him. His primary concern was not "How can I effectively communicate with the people using or maintaining the code I've written?" Instead, his first thought was "How can I slap something together that is quick and easy for me to do?".
Rather than considering it the mark of a professional, he thought of documentation as a burden, an annoying chore, and an opportunity to use his talents to avoid something.
At least he recognized the need for documentation, I suppose.
I've worked with a lot of people who wrote code to one extent or another. Some were full-on C++ programmers, some wrote shell scripts to automate chores, some were like me and landed in the space between those two places.
Some didn't document their code. No comments, nothing except maybe their initials at the top.
Among those, it was a deliberate goal for more than a few. Over time, I noticed patterns. In every language, I saw the same things: needlessly complex logic further clouded with obscure variable names, return codes ignored/no or poor exception handling, ineffective or non-existent code management, an avoidance of standard (for the platform/environment) tools in favor of re-inventing wheels (so the re-inventor could further obfuscate), etc.
I came to understand the people in the subset were joined by one other attribute. They all viewed the obscurity, the lack of technical documentation, of their work as "job security". An AIX admin in an SAP environment said it plainly: If no one else can understand this, then they can't afford to get rid of me (And yes, it's a direct quote as best I remember it)
That's not the attitude of a skilled professional. Charitably, that's an inexperienced person who has yet to comprehend the value of technical communication; if so, then they'll be responsive to requests to adapt and communicate.
However, at worst, it indicates an unskilled hack who's bamboozled their employer (and, probably, a technical leadership blind to the scam). This sort of person actively resists, or is openly hostile to, the idea of documenting their code and participating in effective technical communication; instead, they devote at least as much time and effort to politicking management into letting them get away with it. If that's the case, then it's a place no professional wants to remain.