[SATLUG] culture question

Jason Meridth jmeridth at gmail.com
Thu Aug 28 08:24:51 CDT 2008

In my opinion, you shouldn't have to comment your code.  Code is organic and
I personally never trust comments that are in code.  Nine times out of ten
the original developers or the maintenance developers haven't updated the
comments after they've changed the code.  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.

This has the potential for a flame war, but please understand that my
experience is with enterprise web and desktop applications and also
consumable API code.  I don't code drivers for hardware devices with
embedded C and don't typically deal with ANSI C very often (unless I'm
coding something into the Python interpreter, maybe).

To answer the original question: elegant code is one where a software
developer doesn't have to read comments to understand the code, but in the
case of an API it's where a developer consuming a method can trust that the
method/action has no side effects.  A good read for eliminating the
complexity in some software cases is Domain Driven Design by Eric Evans.  He
speaks more to side effect free functions.

Some people even go as far as saying, "Comments are excuses".  What they are
saying is that you have to comment your code because another developer can't
read it and understand what it's doing.

Jason Meridth
jmeridth at gmail.com
"There is no spoon"

More information about the SATLUG mailing list