A few people point out that they sometimes sketch out code by writing pseudo-code in comments and then writing the real code, which can leave the code in the situation that Kay describes. I've done that too sometimes so I sympathize - but I generally replace a pseudo-code comment by real code, not write the code below the comment.
Anyway, it made me go back over some of my code to see what sort of comments I put in real code. The answer is: "very few". I was actually surprised at how sparse my commenting style is. The code is readable (in my opinion!) because it uses carefully named variables and methods so the code mostly reads like English phrases and sentences. I also generally keep each line of code pretty simple, breaking complex operations into multiple lines where possible.
We all have different styles, of course, but bear in mind that the main audience of your code is probably not going to be you in the future.
And here's an example of some real code I wrote with what I consider a good comment:
some validation on formats:
- should be at least 3 characters
- should be at least two alphabetic
- optionally followed by - and two or three alphabetic
- optionally followed by _ and at least 3 alphabetic
--->
<cfif len(outputSalesOrg) gte 3 and
REFind("^[A-Z]{2,}(-[A-Z]{2,3})?(_[A-Z]{3,})?$",outputSalesOrg) eq 1>
<!--- it's probably valid --->
<cfelse>
<cfset raiseException("INVALID","Unknown sales organization (#arguments.inputSalesOrg#) encountered",arguments.filename) />
</cfif>
Feel free to comment here or over on Kay's blog (to keep the thread in one place, if you want).
I usually just do quick inline comments with my initials to explain anything which is tricky, especially if it's some sort of very proceedural process, or anywhere that a bunch of things happen on one line of code.
I am kind of bad about writing lines of code like this as a method sometimes just to save some typing, but I do usually comment each one of them (snipped from a cffunction):
<!--- BH: Transforms a report struct from the ReportBean into WDDX and sets it within the ReportBean itself ---> <cfreturn getReportBean().setReportWDDX(Struct2WDDX(getReportBean().getReportStruct())) />
(I wonder if that code will show up in a comment or not)
That said, I try to make my comments useful and not too excessive. Where I put in pseudocode, I go back later and revise these into comments that explain what is occured, or remove the text after writing a summary at the top.
[!--- BH: Transforms a report struct from the ReportBean into WDDX and sets it within the ReportBean itself ---] [cfreturn getReportBean().setReportWDDX(Struct2WDDX(getReportBean().getReportStruct())) /]
As for the trim(), I omitted the code (elsewhere in the app) that trims the values I'm getting from an XML message. The code is part of Macromedia's order management system that receives sales orders as XML via file or JMS. As the XML is picked apart, every field is trim()'d so that the rest of the app doesn't have to deal with that.
FWIW, the function begins with:
[cfset outputSalesOrg = arguments.inputSalesOrg /]
Then it does a bunch of validation and transformation of the sales org code to canonical form before returning it. The function is called getCanonicalSalesOrg().
