[SATLUG] culture question

Alan Lesmerises alesmerises at satx.rr.com
Thu Aug 28 20:08:07 CDT 2008

For what it's worth I'll add my own 2 cents here --

I need to comment my code just for myself.  And before anyone says 
anything, it's not because I have a bad memory (quite the opposite).  
It's just that even with relatively self-explanatory naming conventions, 
good structure (indenting, whitespace, etc.), and generally good 
programming practices, many of the projects I work on are complex enough 
that I can't recall  the logic behind every decision I make to code 
something one way versus doing it some other way.  It's also a 
time-saver in the long run.  When I have to revisit that code 3, 6, 12 
months (or more) later, I don't have time to figure out what I 
originally had in mind -- writing a few comments (which usually only 
takes a couple of minutes each) can save me hours the next time.

Also, I usually try to come up with ways to program things to make the 
code run faster & more efficiently.  But that usually means the code 
itself is more cryptic and less self-explanatory.  I'd sooner use one of 
those elegant methods that take only a few lines to perform what would 
otherwise go on for pages simply because I believe that represents 
better programming practice, even if it needs more comments to do so.

I also think that much of the software bloat that's evident in many 
applications these days is the result of choosing to code things to be 
pretty rather than efficient.  But that's just my opinion ...

Al Lesmerises

David Kowis wrote:
> 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.

More information about the SATLUG mailing list