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

[Jonathan Warner]

Heh, I sent a response similar to yours, simultaneously :)

I'm a big fan of self-documenting code. It's fortunate that I'm coding
in mostly Ruby these days, so that helps. I go back and forth on
things such as function/method definition comments to specify a
contract about what the method returns, but typically I only do it to
clarify things for myself at the time. Then I delete them, largely
because I don't want to create comment fossils that don't represent
what the code does, three months or three days down the road.

Actually, in my work environment the fossil comments are the biggest
issue. For example: I've been working on a project for a client for
over a year now, and we've basically been coding their business logic
as they come up with it. They have processes in place, but they're not
documented or they get changed as a normal part of them doing
business.

I took over this project from another developer and found that I was
frequently running into comments that didn't apply to their code
anymore. It was super-confusing while ramping up on the project.
Changing comments to "why" comments (and dating them, sometimes)
actually frames things better mentally, because one can focus on the
code and not get hung up on the comment as the contract when trying to
determine what the codebase does.


Having said all that, I still find myself describing code, specifying
return values, and signing/dating comments on stuff cause it just
gives me a fuzzy feeling.


On Nov 19, 2007 11:12 PM, David Ernst <david.ernst at davidernst.net> wrote:
> 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
>
> --
> 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
>



-- 
Jonathan
http://fleshy.org.nz/yum/