[SATLUG] culture question
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?
> 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
> 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
Having the attitude if *I* can read it, then anyone can is rather egotistic and
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.
More information about the SATLUG