Follow Slashdot blog updates by subscribing to our blog RSS feed

 



Forgot your password?
typodupeerror
Note: You can take 10% off all Slashdot Deals with coupon code "slashdot10off." ×

Comment Under and Over commenting (Score 1) 580

Uncommented code is very often shitty code - and so is over-commented code.

Uncommented code is good if you 1) will be the only person to ever, ever, ever touch the code, 2) you have perfect memory, and 3) you don't expect anyone else on the planet to ever use it.

General rule - assume the person following you is *not* a uber-coding-adept but just some average-joe/jane code-mechanic who has far, far more work on their plate then they can handle already. And this isn't a freaking competition - you **are** allowed to give them a hand in understanding your latest convoluted masterpiece. You usually are on the same team.

At my workplace they have a library of perl code. Most of it is pretty good _code_ and do usefull function. But there is very, very, little comments and the writers simply LOVED to use the latest arcane features of Perl. No subs are documented - "Hey - read the code!".

Sorry but why should I have to read and try to comprehend your convoluted code just to use it? Its *your* responsibility as the author to make sure it does its job and its also *your* responsibility to document (and maintain that documentation) the interface to your code if you expect anyone else to use it. Its *my* responsiblity to follow your documentation and use your code properly.

Also subroutine/module/method comments are often picked up by IDEs to provide on-the-fly documentation (or 'hover-help') for anyone using your code - I'll admit that I find this very useful.

On the Other Hand - there are those who grossly over-comment their code. We have a bunch of these types of people as well.

They Comment every single change and bracket their changes with comments showing the Change Request number as in :

// FR: 1203938+

... Block of new code...

// FR: 1203938-

The results, over time, a patch work of these comments - overlapping each other.... The code ends up virtually unreadable. There are far more lines of these types of comments than lines of code.

Aren't you glad you're not getting all the government you pay for now?

Working...