[SATLUG] culture question

Bruce Dubbs bruce.dubbs at gmail.com
Thu Aug 28 10:30:12 CDT 2008


Jason Meridth wrote:
> In my opinion, you shouldn't have to comment your code. 

So you are a genius and understand all code in all domains without comments.
Go take a look at the code for gzip and try to understand the compression 
methods without comments.

> Code is organic 

What does this mean?

and
> I personally never trust comments that are in code.  

Trust but verify.

> Nine times out of ten
> the original developers or the maintenance developers haven't updated the
> comments after they've changed the code.  

It depends on the culture.  I've seen a lot of bad code.  If the code is bad, 
then the comments really don't matter.  If the code is good, then there are 
probably enough comments to provide an outline.

> Don't get me wrong, I've seen
> teams successfully update their comments and it make it work.
> 
> The only time I see metadata comments being necessary is in the case of
> generating documentation from your code.  This is usually only the case with
> API code; code being consumed by another application.

> The way I get around comments is that I name my methods appropriately.  And
> for those methods that get "big" (past the teams acceptable/understandable
> length), you take portions of the method and extract them to smaller
> methods.  Again making sure those new methods have names that explain what
> the method is doing.

But how long are the names that you use?  Efficient comprehension means that you 
should use tokens that are meaningful, but less than about 12 characters.  This 
is backed by research.

Factoring of code is useful, just like comments.  If a programmer is too lazy to 
add comments, then they are probably too lazy to factor code.  They probably 
just cut and paste similar code and make minor changes.  Of course they are poor 
programmers.

> To answer the original question: elegant code is one where a software
> developer doesn't have to read comments to understand the code, 

Baloney.  The comments are a part of the code.  An important part.

You have to understand that thee are at least two audiences when you write code. 
  The first is the compiler.  The code has to be syntactically correct.  The 
second is the maintenance programmer.  That maintenance programmer may be you 
months or years in the future or someone else that has never looked at your code 
before.

Having the attitude if *I* can read it, then anyone can is rather egotistic and 
usually wrong.

There are whole books written about programming style and I've never seen one 
advocate that comments aren't important.  They are an important tool, just like 
whitespace, naming conventions, and factoring.

   -- Bruce


More information about the SATLUG mailing list