An Architect's View

CFML, Clojure, Software Design, Frameworks and more...

An Architect's View

Stupid Comments?

February 28, 2006 · 5 Comments

I was just reading Kay Smoljak's rant about stupid comments (via a link on Todd Sharp's blog - where he posts a priceless comment found in Ray Camden's code!). Kay rails against people who put "obvious" comments in their code that don't add any value. 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>
The comment adds value because the code is compact and non-obvious (but this is a classic use of regex). I wrote the comment first and then wrote the code. However, since the code in this case is non-obvious, I left the comment in place. Feel free to comment here or over on Kay's blog (to keep the thread in one place, if you want).
View count: 307

Tags: programming

5 responses so far ↓

  • 1 Brandon Harper // Feb 28, 2006 at 11:23 AM

    A Len() that is not hugging a Trim(), oh my! What kind of people are Adobe hiring these days? :) Just kidding of course.

    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):

    &lt;!--- BH: Transforms a report struct from the ReportBean into WDDX and sets it within the ReportBean itself ---&gt;
    &lt;cfreturn getReportBean().setReportWDDX(Struct2WDDX(getReportBean().getReportStruct())) /&gt;

    (I wonder if that code will show up in a comment or not)

  • 2 Lola Lee Beno // Feb 28, 2006 at 11:35 AM

    I'm not sure what's the problem with comments. I do find these helpful, even if there's just a little bit. There's been too many times where I had to debug horribly written code and I had to figure out what was being accomplished by the said code. Even a few lines of comments would have helped.

    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.

  • 3 Sean Corfield // Feb 28, 2006 at 2:38 PM

    Brandon's code looked like this:

    [!--- 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().

  • 4 Sean Corfield // Feb 28, 2006 at 2:39 PM

    Doh! Brandon's code actually did show up in the comment. I had convinced myself that HTML was stripped but obviously I encode it instead...

  • 5 Chris Stoner // Mar 1, 2006 at 5:21 AM

    The problem to me is that ColdFusion (and HTML), being tag based, can have horribly ugly and hard to read code which is not very scannable. I use comments as visual break points to segment my code into paragraphs even if they have little &quot;deep&quot; value. This makes it easier to quickly see the code from an executive summary perspective, thus in my opinion making it easier to maintain. Just because the code is simple it doesn't make it readable especially to entry level developers.

Leave a Comment

Leave this field empty: