[ubuntu-us-in] Is Commenting Ideal? (was: Re: Time for a change)

[David Ernst]

Actually, for the sake of conversation, I'll present that I've really
become more of a believer in this ideal:

"One might more accurately say that we think the code, properly
crafted, is the best documentation."  

I first read this stunning concept in Bertrand Meyer's seminal work,
Object-Oriented Software Construction.  Up until then, every
programming text I ever read nagged incessently about documenting code
well.  Now when I find myself writing code that I think might be
confusing to other programmers, I start a comment, but then I think
"maybe I should just rewrite the code so that what it's doing is more
obvious".  Sometimes I do, and I like it.  Sometimes I'm too lazy, or
it would be difficult or impossible to succeed at that goal, so I
write a comment (curiously, this is often when I'm doing something
that I feel bad about...).  And sometimes, I'm sure, I just write code
that's hard to understand.  Probably all too often.  :(

Still, this isn't a message about my own practices, this is a message
about what the ideal should be.  What's undeniable is that people
should produce source files that are easy to understand.  The question
is, when are comments the best way to achieve that goal?  And, I must
say, when I see code written nicely in a nice readable language (like
Ruby or Python) I can even find the documentation annoying.  I want to
emphasize, though, that most code is not written well enough to
satisfy this request, and it's much better to document it than to just
leave it confusing...  

Thoughts?  

David


On Mon, Nov 19, 2007 at 10:49:19PM -0500, Simón Ruiz wrote:
>Yes, please...and this is to all of you who write, or will ever write
>any sort of code.
>
>One day, someone may have to debug your code, so for Love's sake, COMMENT IT.
>
>At least explain your basic logic, what each "chunk" of your code is
>for, what to expect from functions, etc.
>
>Uncommented code is a pain to wade through...
>
>On the other extreme, there's no need to comment like this:
>
># Ask the user whether the want to play a nice game of Chess.
>playChess = raw_input('Do you want to play a nice game of Chess?')
># If they don't say no
>if playChess != 'n' and playChess !=  'N':
>    # Play Chess
>    Chess.play()
>
>If you catch my drift. This will just train people (including
>yourself) to ignore your comments.
>
>Simón
>
>On Nov 19, 2007 10:21 PM, Rob Ludwick <rob at rcludw.no-ip.org> wrote:
>> Python... it's easy to program in.  Too easy.  Debugging other's code
>> can be a challenge because type and function obfuscation is part of the
>> language, and programmers don't always document their code clearly.
>
>-- 
>Ubuntu-us-in mailing list
>Ubuntu-us-in at lists.ubuntu.com
>Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/ubuntu-us-in