the comments in the document - thats where they are supposed to be! Comment size is the least of my worries, 20k vs 10k vs my 500GB drive?..vs..2hrs @ $120/hr figuring out exactly why we used a linked list or not?

“#

That basically means that if you have a block of code that have a comment, extract the code to a method and name it according to what it does. If it’s already a method, rename it to better explain it’s purpose.

#”

that only works if your naming convention is totally logical AND the procedure/method only does one thing (and one thing only ) throughout the life of the code…

The real issue is that code editing systems are only just beginning to find the issues and needs for commenting and editing code!

After all these years, we have only recently gotten color syntax highlighting and brace matching. .NET allows you to collapse/expand blocks and new addons allow you to mark a block of text and then specify the block of code the comment refers to.
A checksum is generated for the code block, and as subsequent revisions take place, the icon beside the comment block changes color and shape to indicate its diverging relevance to the code it comments!

also, like Microsoft word, we can now see different revisions from other people (or yourself) as markup tags within the document.

…popup and insertable “to-do lists” and reviewer notes/comments embedded in the code are really items that need the support of the Code IDE and the poor developer shouldnt be forced to keep track of all this :)

I agree wholeheartedly that uncommented code can be a nightmare. There are actions that are just too complex to read in code. Watching a piece of code toss around ambiguously named variables often leaves me tearing my hair out trying to follow them.

However, overcommented code is also frustrating to read as a new developer because instead of “what?”, “why?” or “how?”, I start having to ask myself “where?” In my opinion, that’s a question that shouldn’t come up when I’m reading code. When I’m trying to understand the hows and whys of a program, I’m not interested in looking for Waldo in the land of ASCII.

Comments also expand the size of a document to somewhat ridiculous proportions if you’re counting one line of comment per line of code. We’re talking at least double the length of the actual code document. There’s nothing more intimidating to a learning developer than to open up someone’s program to see how it works and having to use a magnifying glass to find the scroll bar on the right side of the screen!

I think the important thing is to find a balance between using explicit naming conventions and commenting your code. Let your code speak for itself where it can, and give it a hand with good, clean comments where it can’t. Try to bear in mind that the people reading your code are probably also proficient in the language you’re using to at least some extent.

The Refactoring approach is fair enough - certainly it helps to use method and property names that are as self-explanatory as possible, but that doesn’t address the key purpose of commenting, which is to explain *why* you’re doing something, not just what. Somehow, this just doesn’t cut it for me:

Some would say, myself included that the code it’s self should explain what it does, which is far better than any commenting system you could have.

Conversely, this is but one reason as to WHY you should have unit tests, which are their own documentation, that being one of many benefits. I could argue all day as to why your idea is bad but I’m not going to.

In any case if you were to unit test you wouldn’t be dependent on comments to the extent that your now implying.

As Tim said, commented code is very hard to maintain.

If someone changes code, and it breaks, you know that someone changed the code. But you have no way of knowing when someones changes the comments or not, and if he doesn’t, how does the next developer that has to change the code will find himself with a text saying that the code should do something and a code that does something else.

Now, who’s right?

Solving this issue is trivial.

Quoting Martin Fowler’s Refactoring:
“If you need a comment to explain what a block of code does, try Extract Method. If the method is already extracted but you still need a comment to explain what it does, use Rename Method. If you need to state some rules about the required state of the system, use Introduce Assertion.”

That basically means that if you have a block of code that have a comment, extract the code to a method and name it according to what it does. If it’s already a method, rename it to better explain it’s purpose.