[SATLUG] Re: culture question (Bruce Dubbs)

David Kowis dkowis at shlrm.org
Thu Aug 28 14:03:54 CDT 2008

Quoting Jason Meridth <jmeridth at gmail.com>:

> Prefix to your comments:
> I do Test Driven Development (TDD).  I let me tests comment my code.
> Another developer can easily run my tests and see what the code is doing.
> Once in the source my method names say what they do (comment below about
> Bruce's 12 character limit)
> Bruce, I respect your experience and your position.  Your response bothered
> me.

I know I don't say much on this list and often I disagree with Bruce,  
but I agree with most (if not all) of what he says.

>> 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.
> Don't put words in my mouth Bruce.  I never said I was a genius.  Don't be a
> jerk.  Notice, the prefix "In my opinion".
>> > Code is organic
>> What does this mean?
> Code changes a lot.  Especially when you refactor your code based off new
> features/defects/requirements.  Common sense.

Common sense, isn't. I figured out that "organic" meant that it  
changes a lot, grows, if you will. But, it could've meant something  
else if one were to read into it too much.

>> 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.
> Thank you for re-iterating what I say below this.
>> 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.
> Can you provide link to the research please.  We're not coding on 512K RAM
> PCs anymore.  You don't have to limit your method names.  Please don't give
> me the "waste of resources" speech.  I'm sick and tired of hearing about
> geriatric ways of coding.  It's one of the many reasons I leave this mailing
> list on and off.  I love the group, but the backlash when a younger person
> comes in and expresses ideas, and gets slammed, is unprofessional and
> non-conducive to a non-profit user group.

He's not talking about computer resources, he's talking about people  
resources. it's difficult to process and remember method names longer  
than 12 characters for most people. Similar research backs why phone  
numbers aren't longer than 10 digits, and before that 7. It's easy to  
remember 7 digits, that's about all the brain can do.  I really think  
you're reading into what he's saying too much, you're taking it  
personally. He never said anything at all about "wasting resources."

> There is no such thing as a silver bullet.  If the team agrees on comments,
> so be it.  I can prove that you don't need them to make successful,
> maintainable code.
>> 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.
> Your lazy comment is also a stab.  When a board member responds like this,
> it's shows what the higher membership of the group contains.

I didn't think this was a stab either. Just that a lazy programmer is  
a crappy programmer. And that he believes that comments are useful.  
Don't take things so personally...

>> 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.
> Unit testing is more important and with it, comments are not necessary (IN
> MY EXPERIENCE, I'll start putting this after every opinionated statement).
> Expression of opinion on this group sucks.  When a board member responds
> like this...  come on and have a mature conversation.  Next time, I'll just
> submit a summary of my experience.

I might believe that. Tact isn't one of my strong points. Especially  
since you can't read expressions or get inflections over email ;)  
Emoticons are your friend. Not *everything* Bruce says is a personal  
attack :P

>> 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.
> One of my favorite quotes is, "Code as if the guy who is going to maintain
> your code is a psychopath and knows where you live."  I live by it.
>> Having the attitude if *I* can read it, then anyone can is rather egotistic
>> and
>> usually wrong.
> Are you calling me egotistical?  That is not the attitude I was trying to
> convey.  Maybe a SATLUG meeting on coding standards??  Ultimately they are
> decided by the team, but global standards can be discussed.

Jeez, chill out. That's his opinion. Just like it's my opinion that  
you should chill out. /me notes this will probably end up being a  
flame war, and I should've kept all my opinions on thick-skinnedness  
to myself. :(

>> 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.
> What are the copyright dates on the books?

I would expect them to be fairly recent.

I think the issue here is style of coding. There are ways of writing  
code that "don't require documentation." The example I can think of is  
the source code to the Hacker's Diet Online. it's written using a  
style of perl that's supposed to be self documenting. I found it very  
difficult to read. It was not simple, it was really very complex. Not  
really self-documenting in my mind. You can probably write code that  
doesn't need documenting, but what if you have to do something odd  
with a segment of code? How do you document, without comments, that  
the API you're talking to doesn't quite behave the way it's  
documented, so you have to do this block of work-around to make it  
behave in a nice way?

Commenting things like //Increment count
That's a bit ridiculous, but applying a comment to a block of code as  
to the reasoning behind the block, or why the block is ordered a  
certain way is difficult to do without comments. At least, that's the  
examples that I think of, and where I think commenting is important.

David Kowis
Source Mage Linux - www.sourcemage.org
Liberty! - www.campaignforliberty.com

More information about the SATLUG mailing list