Documentation Schmocumentation

by Krishna on January 12, 2012 at 11:20 pm

Random

I was inspired by an article I read over at Coding Horror. I’ve always believed documentation to be a crucial part to the software development process, but a case can be made against excessive documentation actually cluttering the code base. Thoughts?

-Krishna

Mike

It depends on how obvious the code is in my opinion.

If you have a function that is called via: “parse_data_input( $input );” (I mostly use PHP, hence the $). That is a bit obvious. However if you have “fix( $text );” do the exact same thing, it isn’t as clear.

Over documentation can be just as bad as under documentation as far as I am concerned.
Sebastiaan Stok

I had topic about this yesterday (in Dutch btw) :)

A quote.

Try to limit the number of comments, only if something is unclear, you should you describe therm. Things like this.

// Chmod file
chmod ($ filename, $ this -> _rights);

Is unnecessary.

Good example.

// Since We Already validated if length is legal, and no illegal characters are Given it’s save to Assume it is legal
elseif ( strpos ($ pmInput, ‘.’) === false)

And

// If there is no character range, do not bother trying to make sense of the input
if (empty ($ sType) & & strpos ($ sValue, ‘-’) == false)

Here I explain why this is done.

* Do not use short function names like “setF. What is ‘F’?
File, function, format, form, etc.

I have written en very advanced article about the topic of clear programming. Google Translate seems to make it ‘readable’, but its not perfect.

http://translate.googleusercontent.com/translate_c?hl=nl&rurl=translate.google.com&sl=auto&tl=en&twu=1&u=http://www.pfz.nl/wiki/overzichtelijk-programmeren/&usg=ALkJrhjGKQ6Jp4r-TbtTG97lkaQZmyPtTg#documenteer-bijna-alles
http://kevinrubin.blogspot.com Kevin Rubin

At one time I was big on documenting code, but over the years (I’ve been a software developer professionally for 20 years, including 10 years with one code base) I’ve come to decide that minimal documentation is best…

I’ve been with my current company for a bit over a year, working on code that’s about ten years old, and it’s extensively documented. Unfortunately about 75% of the comments in the code are wrong. They may have been correct at one time, but past developers have changed the code, sometimes refactoring, sometimes adding or removing functionality, sometimes changing, sometimes just fixing bugs, but not maintained the comments…

An eye opening experience I had was about four years ago. We had a big hand-off of a lot of code from a team to whom we’d outsourced the work. Our team was scattered, some of us in India, some of us in Oregon and the most senior developer at his home office in Halifax, connected by speaker phones and using desktop sharing.

That senior developer was a fanatic about commenting code. He expected every line of code documented. Even obvious ones like simple counter increments…

So we were in this meeting, in the middle of the night for those of us in India, and the outsource team was trying to explain what it did, some stuff about managing multiple threads of things in our application. We spent hours arguing over it, and couldn’t agree what the result of it was, and people were getting angry, and it was late, those of us in the meeting at the end of our workday were getting cranky…

We finally realized what the problem was… Most of us were reading the code on the screen, while the senior developer was reading the comments, not the code, and the comments were wrong!

Anyway, we’re not in the 80′s anymore where lots of languages had 2 character limits on variable names, so we can use good description names to make the code as nearly self-documenting as possible.

The crap I’m working with now has lots of bad names. Collections are named “c”, for instance, Lists are named “l” and things like that. With 1,000 line methods, it’s easy to lose track of the fact that “c” contains Products (and comments say “get next object from c”). I try to rename them when I’m working on code, so the next person doesn’t struggle as much…
David

Sounds to me like someone watches Wordgirl on PBS. LOL
- http://www.pcweenies.com Krishna
  
  Guilty as charged. :D
Seamus

I would say that comments are still needed, though I do agree that they are not needed for every little thing. If you put good variable names into your program you will need less explaining of what you did.

Though to make comments valid you need to update them when you are asked to go into a program and either expand what it does or just getting it up to date…..When you don’t is when people get really tired of comments that make little sense.

I feel for those who have to wade through code that has bad comments and variable names that make little sense…..It has to be one of the most frustrating things to go through.
PCTechYoda

While I’m certainly not a code expert, I come from the other side of the industry, the support side. In my early days as an Apple Mac specialist, back in the days of OS 9 and the beginning of the OS X transition, I’d run into clients that had previously been supported by another local consultant and was appalled at some of the “job security” things I’d run into.

Some of my favorites were:
1) Flagging the System Folder as “invisible” (and, unlike Windows, on Mac OS 9, it wasn’t so simple to find and un-invisible invisible objects, you’d need a non-standard program like ResEdit to do it)

2) Completely deleting control panel programs after applying initial settings so they couldn’t be changed again

3) Locking down administrative options with passwords unknown to the computer owner

I personally prefer that my work stand on its own merits and my clients keep employing me because I do a good job, not because I built some catch into their system to make it difficult – if not impossible – for another person to step into my role.

Ethics in IT is an interesting topic – I wonder how many rather large organizations are at the complete mercy of CIOs, IT Directors, and independent consultants that hold the keys to the very lifeblood technology that fuels them, that a single person could literally put such an organization out of business if crossed.
MasterMacMaverick

Here’s a better site for things like this and more:

http://thedailywtf.com

Enjoy! I do.

The PC Weenies

Documentation Schmocumentation

Similar Posts: