Commenting your code is a Best Practice, but if my comments are in the way, turn them off

So it seems like a lot of people have been weighing in on the discussion of code commenting. Well I thought I would throw in my two cents.

I agree with Ben

Now that we've go that out of the way. I also agree with one aspect of the argument not to comment. And that is that sometimes comments get in the way of reading code and figuring out what it does. But does that mean we should stop commenting our code? I say no. Instead, if I feel that comments are in the way, I turn them off.

Now, there is not a button to turn off comments in Eclipse (at least I don't think there is) but there is a relatively simple way to make them virtually invisible.

First, go into Window>>Preferences (Don't know if this is different on Mac or Linux) and go into your options for CFEclipse.

Set your CFML Comment color to White:



Turn on Code Folding for comments and set the minimum number of lines to 1.



Now you can turn really verbose comments(like in Luis' ColdBox.cfc):


Into no comments:



And if you do want to read the comment, you can expand and highlight:

Comments
Jim Priest's Gravatar Interesting - it seems there should be a way (I have no idea how) to make a button that turns comments on/off.
# Posted By Jim Priest | 6/5/08 11:23 AM
Jason Dean's Gravatar That would be really cool, Jim
# Posted By Jason Dean | 6/5/08 11:33 AM
Brian Kotek's Gravatar I hadn't thought of just "whiting out" the comments, that is an interesting option. But the issue doesn't really have anything to do with reading the code (at least to me).

The issue is that many comments are either redundant or are a duplication of information. So not only do comments often indicate that something is too complicated, but they also make maintenance more difficult because the comments have to be updated every time the code changes. If the code is clear and self-documenting, this problem is eliminated. So comments are great when used judiciously, but redundant comments or comments that are necessary to explain overly complex code should be avoided.

thanks,

Brian
# Posted By Brian Kotek | 6/5/08 1:10 PM
Jason Dean's Gravatar @Brian - I can certainly agree that having to update comments with code changes is a pain, and half of the time I forget, I also hate writing comments that almost word-for-word repeat the code.

I guess one consolation is that with OO development we will likely be spending less time changing our code (hopefully).

As for self documenting code, I agree that it is probably safe to leave the comment off of:

<cfset salesTaxRate = "0.0625" />

There certainly is a lot more to the discussion, and I understand where you are coming from, but I do recall someone in the posts today talking about the readability of commented code, and that is what I was looking to address.
# Posted By Jason Dean | 6/5/08 2:07 PM
BlogCFC was created by Raymond Camden. This blog is running version 5.9.1. Contact Blog Owner