Slashdot stories can be listened to in audio form via an RSS feed, as read by our own robotic overlord.

 



Forgot your password?
typodupeerror

Comment: Under and Over commenting (Score 1) 580

by CrazyFool (#30625574) Attached to: Myths About Code Comments

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.

Possessions increase to fill the space available for their storage. -- Ryan

Working...