Even if this is not directly about Ruby, both Jeff Raskin and the subject have come up before on this n.g. so I believe it's not altogether off-topic...
Comments Are More Important Than Code
http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290
Tim Hunter wrote:
Even if this is not directly about Ruby, both Jeff Raskin and the subject have come up before on this n.g. so I believe it's not altogether off-topic...
Comments Are More Important Than Code
http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290
Yes, but...
A few days ago, I noticed that a method in the Squeak (Smalltalk) core collection classes did one thing, while its comment said another. That method has probably been around for thirty years or so; the Smalltalk collection classes have a long history.
Which is correct? The code, because the behavior takes precedence, or the comment, because it expresses the intention?
I don't know the answer; nobody on the Squeak mailing list has yet responded to my query about whether the code should be changed or the comment.
Jim
--
Jim Menard, jimm@io.com, http://www.io.com/~jimm
"Indeed, an upsettingly large part of academia right now seems to be
working on bringing Java into the 1980s... sigh." -- Avi Bryant
"Tim Hunter" <sastph@sas.com> schrieb im Newsbeitrag
news:d4o1i0$bd3$1@license1.unx.sas.com...
Even if this is not directly about Ruby, both Jeff Raskin and the
subject have come up before on this n.g. so I believe it's not
altogether off-topic...Comments Are More Important Than Code
http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290
There's some truth in this.
"Many become so laconic that you have to understand the code to be able to
interpret the comment." - very nice. 
"Ideally, comment should be the default, with a way to signal the
occasional lines of code." - sounds like he would be a friend of
http://www.literateprogramming.com/ and especially
http://www.ross.net/funnelweb/
Kind regards
robert
This is something of a Straw man argument. In the article Raskin says:
"I discard the radical position taken by proponents of extreme programming (XP) to get rid of 'unnecessary' documentation."
To which you have to ask, "Why would you want to write unnecessary documentation? surely you have better things to do, like write necessary documentation?".
A more productive debate would not be about the false dichotomy of comments vs no-comments but about what comments should be for and what level is 'necessary' and what level is 'sufficient'.
Personally I don't document algorithms (unless they are particularly obscure) but I try to documemt the responsibility of a classes/modules and the intent of methods (unless theyy are so well named it is obvious). Generally I find that this is sufficient; furthermore responsibilty and intent change slowly enough that the documentation doesn't drift out of line with the code.
Tom
Tim Hunter wrote:
Even if this is not directly about Ruby, both Jeff Raskin and the subject have come up before on this n.g. so I believe it's not altogether off-topic...
Comments Are More Important Than Code
http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290
"Tim Hunter" <sastph@sas.com> schrieb im Newsbeitrag news:d4o1i0$bd3$1@license1.unx.sas.com...
Even if this is not directly about Ruby, both Jeff Raskin and the
subject have come up before on this n.g. so I believe it's not
altogether off-topic...Comments Are More Important Than Code
http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290
--
Comments and everything like represent the "requirements", code is - in principle - nothing else than the
concrete realization. It may sound strange but the user (probably not the programmer) is interested in
requirement.
Wolfgang Nádasi-Donner
wonado@donnerweb.de
I actually sat down and read this artcile. I'm blown away by some of
the things he said. I'm so blown away that I am going to rant a little.
I hope no one minds. <:)
For example:
Any language or system that does not allow full flowing and
arbitrarily long comments is seriously behind the times. That
we use escape characters to "escape" from code to comment is
backwards. Ideally, comment should be the default, with a
way to signal the occasional lines of code.
What he said up there, that's crazy talk. Ramblings about Literate
Programming aside, the idea that documentation should come before code
is a serious mistake. Documentation exists to *document code*, code
does not exist to follow documentation.
Then he rambles about "bad" comments and makes some trivial examples.
Then he puts in an example which he asserts is good, but doesn't really
justify why it's good to explain your algorithm choice in the code.
It's not unreasonable to name algorithms or patterns in your code, but
the "why" has no place in there, because that "why" is subject to
change and is outside the scope of the program itself.
If you want to explain why you did something, that's what a whitepaper
or tech memo is for. Your code isn't the place to justify your position
post facto. The fact that the code works should be justification
enough.
Inevitably, the documentation-heavy approach (comment-driven
development) leads to a design-up-front methodology. And I think we
have a mountain of evidence that the Waterfall Method and similar
up-front design methodologies are impractical at best.
I'm a big fan of documentation and code that lends itself to the
reader, and Ruby helps me with this, but my feeling is that if your
methods are so long that they require comments, then your methods are
too long. Sure, there are exceptions to this (explaining a tricky step,
saying why a non-obvious piece of code exists, naming a pattern or
algorithm), but in general I think this is a reaction to bad coding
practice.
I really like the Ruby communitiy's approach to documentation. Document
*what* functions do, give examples of class usage, provide rich unit
tests. But seldom do I see a project give step-by-step comments,
explain what variables are (beyond their name), or explain motiviations
in the code. This means we have beautiful Rdoc outputs and clean code.
Strictly speaking, the Rails documentation would fail this guy's
criterion for good documentation. But I think pretty much anyone who's
used Rails (and gotten past the awkward, "Where do I start" step) can
testify that the Rails documentation is complete and well-done.
Tim Hunter wrote:
Even if this is not directly about Ruby, both Jeff Raskin and the
subject have come up before on this n.g. so I believe it's not
altogether off-topic...Comments Are More Important Than Code
http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290
I have reported this heretic to the Agile Authorities.
The standard reply is "show me some code [and its tests] that you think need
a comment."
You typically find something to refactor long before you even get to the
comment...
--
Phlip
http://www.c2.com/cgi/wiki?ZeekLand
Jim Menard wrote:
Tim Hunter wrote:
Even if this is not directly about Ruby, both Jeff Raskin and the subject have come up before on this n.g. so I believe it's not altogether off-topic...
Comments Are More Important Than Code
http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290
Yes, but...
A few days ago, I noticed that a method in the Squeak (Smalltalk) core collection classes did one thing, while its comment said another. That method has probably been around for thirty years or so; the Smalltalk collection classes have a long history.
Which is correct? The code, because the behavior takes precedence, or the comment, because it expresses the intention?
Ideally, in CDD (comment-driven development), the comments would be written first, then the code (including unit tests) written in such a way that comments are not needed to describe behavior (though they may still be needed to explain design trade-offs or a broader intent).
I don't know the answer; nobody on the Squeak mailing list has yet responded to my query about whether the code should be changed or the comment.
A problem, but without the comments there may possibly be incorrect code with no (obvious) indication that something might be askew.
(One might hope that unit tests would allow the dubious code to be changed and tested to see which is correct, the comments or the code.)
James
amen. i've always felt that the whole comment thing breaks down in two ways:
- syncing, which you're showing here
- ambiguity : english (any human lang) is ambiguous - code is not.
obfusicated mabye, but ambiguous no.
not that comments are a bad thing - but the source is the authority so, if you
can read it, why look elsewhere? i think that, as languages become more and
more VHL we'll see less and less commenting - i already feel that it's __ok__
(though not ideal) to not doccument a small to medium bit of ruby intended for
developers since, in that specific case, the end users can get the most
accurate view of the code from the code itself whereas in the case of say, the
gnu scientific library written in reams of c, doccumentation is essential. i
think discussions of the merits of comments must be framed within a specific
computer language since that computer language can contribute or detract from
any meaning conveyed by english (or other) docs.
2cts.
-a
On Wed, 27 Apr 2005, Jim Menard wrote:
Tim Hunter wrote:
Even if this is not directly about Ruby, both Jeff Raskin and the
subject have come up before on this n.g. so I believe it's not
altogether off-topic...Comments Are More Important Than Code
http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290
Yes, but...
A few days ago, I noticed that a method in the Squeak (Smalltalk) core
collection classes did one thing, while its comment said another. That
method has probably been around for thirty years or so; the Smalltalk
collection classes have a long history.Which is correct? The code, because the behavior takes precedence, or the
comment, because it expresses the intention?I don't know the answer; nobody on the Squeak mailing list has yet responded
to my query about whether the code should be changed or the comment.
email :: ara [dot] t [dot] howard [at] noaa [dot] gov
phone :: 303.497.6469
although gold dust is precious, when it gets in your eyes, it obstructs
your vision. --hsi-tang
===============================================================================
That is a straw man, removing the quotes around the word unnecessary to change the meaning. Clearly Raskin doesn't agree that it is unnecessary, if he did he wouldn't have put the word in quotes.
I agree with your comment about "what comments are for".
Stephen
In message <d4o6vp$qj2$4@newsg2.svr.pol.co.uk>, Tom Ayerst <twa@post.com> writes
"I discard the radical position taken by proponents of extreme programming (XP) to get rid of 'unnecessary' documentation."
To which you have to ask, "Why would you want to write unnecessary documentation? surely you have better things to do, like write necessary documentation?".
--
Stephen Kellett
Object Media Limited http://www.objmedia.demon.co.uk
RSI Information: http://www.objmedia.demon.co.uk/rsi.html
Jim Menard wrote:
I don't know the answer; nobody on the Squeak mailing list has yet responded to my query about whether the code should be changed or the comment.
Presumably less code would break if the comment is changed rather than the implementation.
Well said.
I love the idea of documentation-style commenting. It's truly a nice
"in a perfect world" concept. However, I can imagine how much extra a
nightmare it would be for a coder to be hacking away and then have to
step outside of that mindset to fiddle with the english language and
fix comments.
Just who would be writing and maintaining all that "commenting"
anyways? The programmer is who.. so its style follows the
programmer's mindset.. concise.. so they can move on to the next real
issue --> more programming.
As soon as coders start leaning towards documentation.. the entire
"programming" thing suffers.. unless there's some sort of freakish new
vat-grown breed of programmer+documenter that I'm not aware of.
Well.. ruby might be easy enough on the brain that it leaves more time
to think about such things. Scary.
On 4/27/05, Dave Fayram <dfayram@gmail.com> wrote:
I'm a big fan of documentation and code that lends itself to the
reader, and Ruby helps me with this, but my feeling is thatif your
methods are so long that they require comments, then your methods are
too long. Sure, there are exceptions to this (explaining a tricky step,
saying why a non-obvious piece of code exists, naming a pattern or
algorithm), but in general I think this is a reaction to bad coding
practice.
Dave Fayram wrote:
I actually sat down and read this artcile. I'm blown away by some of
the things he said. I'm so blown away that I am going to rant a little.
I hope no one minds. <:)For example:
Any language or system that does not allow full flowing and
arbitrarily long comments is seriously behind the times. That
we use escape characters to "escape" from code to comment is
backwards. Ideally, comment should be the default, with a
way to signal the occasional lines of code.What he said up there, that's crazy talk. Ramblings about Literate
Programming aside, the idea that documentation should come before code
is a serious mistake. Documentation exists to *document code*, code
does not exist to follow documentation.
Hmm. I often see code as being documentation dumbed-down enough for computers to understand.
Positing that documentation exists to document code, and that code does not exist to follow documentation, is begging the question.
James
Dave Fayram wrote:
If you want to explain why you did something, that's what a whitepaper
or tech memo is for. Your code isn't the place to justify your position
post facto. The fact that the code works should be justification
enough.
Yeah; I've written lots of code that, um worked. It just worked at the wrong thing.
Inevitably, the documentation-heavy approach (comment-driven
development) leads to a design-up-front methodology. And I think we
have a mountain of evidence that the Waterfall Method and similar
up-front design methodologies are impractical at best.
I don't see how one goes from writing comments to having a documentation-heavy approach. Or how it equates to up-front design.
I'm a big fan of documentation and code that lends itself to the
reader, and Ruby helps me with this, but my feeling is that if your
methods are so long that they require comments, then your methods are
too long. Sure, there are exceptions to this (explaining a tricky step,
saying why a non-obvious piece of code exists, naming a pattern or
algorithm), but in general I think this is a reaction to bad coding
practice.
But a better approach might be to write the method comment first, then convert the comment to code, such that the comment is no longer needed. And if you find that you cannot do this, then that may be a code smell.
Or, the comments that remain are higher-level observations that have no code equivalent, and should stay.
I believe that developers can forget that what seems obvious at the time the code is written will often seem cryptic later on, ever to the one who wrote it. Writing it down forces you to at least make the point explicit, and help the coder see if he or she has a clear understanding of what code is supposed to do.
I find the a best way to know if I understand something is to try to write about it. It forces me think in a certain way that talking or coding does not.
Writing is a unit test for the brain.
I really like the Ruby communitiy's approach to documentation. Document
*what* functions do, give examples of class usage, provide rich unit
tests. But seldom do I see a project give step-by-step comments,
explain what variables are (beyond their name), or explain motiviations
in the code. This means we have beautiful Rdoc outputs and clean code.
That's great when it happens. But there is too much core ruby rdoc that simply gives an obtuse method and a set of terse variable names. Not a word on what the method does.
Strictly speaking, the Rails documentation would fail this guy's
criterion for good documentation. But I think pretty much anyone who's
used Rails (and gotten past the awkward, "Where do I start" step) can
testify that the Rails documentation is complete and well-done.
Not everyone agrees with that. I'm past the "Where do I start" step and routinely have problems understanding how to do what should be simple tasks.
James
Stephen Kellett wrote:
"I discard the radical position taken by proponents of extreme programming (XP) to get rid of 'unnecessary' documentation."
To which you have to ask, "Why would you want to write unnecessary documentation? surely you have better things to do, like write necessary documentation?".
That is a straw man, removing the quotes around the word unnecessary to change the meaning. Clearly Raskin doesn't agree that it is unnecessary, if he did he wouldn't have put the word in quotes.
Kind of, but Raskin was distorting the XP position by putting the quotes in in the first place. The XP position really is, "get rid of unnecessary documentation", which is quite sensible (huge amounts of documentation _is_ just written and never read, or left to get pathologically out of date. By putting the quotes in, Raskin was trying to suggest that their definition of uneccessary was wrong, which is a quite legitimate debate to have, as I said further down. But by being unable to resist having a poke at a methodology he doesn't like he moved the argument to a "do comment"/"don't comment" level. Which was my point.
I agree with your comment about "what comments are for".
Thanks, it works for me.
In message <d4o6vp$qj2$4@newsg2.svr.pol.co.uk>, Tom Ayerst > <twa@post.com> writes
Stephen
Sy wrote:
Just who would be writing and maintaining all that "commenting"
anyways? The programmer is who.. so its style follows the
programmer's mindset.. concise.. so they can move on to the next real
issue --> more programming.As soon as coders start leaning towards documentation.. the entire
"programming" thing suffers.. unless there's some sort of freakish new
vat-grown breed of programmer+documenter that I'm not aware of.
Wow, and I was wondering where the phrase "code monkey" came from! Well, that's cleared up.
The coders ARE the ones who can document the choice of algorithms and explain why the function was written at all. I've had to work on a lot of legacy, undocumented code and it is difficult. It wastes more of my time that it would have taken the writer to describe things well. Is the original coder thinking of the maintainers? No, not in this "me" generation. Not in this "obfuscated code" generation ( hey, if you have trouble understanding this code I wrote then you must not be as smart as I am! I win! )
Barry
James Britt said:
Positing that documentation exists to document code,
and that code does not exist to follow documentation,
is begging the question.
I am sitting on a bench at a train station next to you. We are both
waiting for a train to show up. I'm explaining to you how these
"modern" trains work, and it's all you can do to not to fall alseep as
I explain it in complete, mindless detail. Then suddenly I stand bolt
upright. Off in the distance, you can see the train.
"Holy smokes, the backwash distillerifier has an inversion field
surrounding its nebulae!" I exclaim, pointing vigorously. "That train
is going to blow up." The train shows up, stops, picks us all up, and
goes about its merry way. I still continue to ramble, "This makes no
sense. With that inversion field eating its camera obscura, the
vivacity of the engine should make it a portal to the plane of fire..."
and so on.
Who is wrong? Me, because my explanation was wrong, or the train,
because it didn't behave the way I explained it would? The train meets
its requirements. It got us from point A to point B. But for some
reason my expert knowledge of trains has been invalidated (probably by
windmills and sky-punching, but let's not go there).
Documentation can lie. Code cannot lie. Therefore, the code is
authorative.
James Britt wrote:
Dave Fayram wrote:
> Your code isn't the place to justify your position
> post facto. The fact that the code works should be justification
> enough.Yeah; I've written lots of code that, um worked. It just worked at
the wrong thing.
So documentation would solve this problem? I don't think so. Unit tests
solve this problem to the extent that any modern solution can.
Documentation is just as likely to lead you astray as help you here.
I don't see how one goes from writing comments to having a
documentation-heavy approach. Or how it equates to up-front design.
In your next statement you claim you should write the documentation for
a method first, then "convert" it to code. I maintain that this is
"design-up-front". I've had plenty of scenarios where I think I know
exactly what I'm about to code, and then in the process of coding it I
realize that I had it all wrong, overlooked something, etc.
And please observe, I am not against writing comments. In all the code
I write, I'm usually the first to document my signatures and I prefer
to put examples in wherever I can find an excuse.
But a better approach might be to write the method comment first,
then
convert the comment to code, such that the comment is no longer
needed.
And if you find that you cannot do this, then that may be a code
smell.
Maybe it is a smell, but it's the good kind that lets you steer your
code based on what it needs to be, not what you think it ought to be.
See the comment above.
I think what you're describing is not only a headache, but inefficient.
If applicable, I'm already writing unit tests. When I'm convinced that
I haven't made a misstep, I'll document it.
Documenting untested code (as in, explaining in english an algorithm or
procedure which has yet to be tested, which is a necessity of your
approach as described above) is a waste of time and effort. If you're
wrong, you now have that much more information to change.
I believe that developers can forget that what seems obvious at the
time
the code is written will often seem cryptic later on, ever to the one
who wrote it. Writing it down forces you to at least make the point
explicit, and help the coder see if he or she has a clear
understanding
of what code is supposed to do.
I believe this is a reaction to poor coding practice, and not a
necessity. I've picked up code that I wrote years ago and managed to
step in with only minor headache. I don't think I'm special, or have
any super-brain-abilities that let me do this. I just happened to work
with someone who made me code with good style and document
appropriately. There was nothing special about it (unless you deem a
college research product being maintainable as special, which it may
be).
Oh, and we had a readme explaining what the code did at a higher level
(*cough*techmemos*cough*).
I find the a best way to know if I understand something is to try to
write about it. It forces me think in a certain way that talking or
coding does not.
Funny, I find the best way to understand it is to *do* it and *test* it
and *try* it. Then, if it seems right and holds water, I keep it. If
not, then I made a mistake and obviously I need to recode it.
For me, unit tests as test first serve the function you are describing.
That's great when it happens. But there is too much core ruby rdoc
that
simply gives an obtuse method and a set of terse variable names. Not
a
word on what the method does.
No fair making a point that I agree with, and spinning it like I don't.
I'm not arguing that documentation is useless. I'm arguing that the
essay mentioned above goes too far, and that Literate Programming is
something I find pointless and inefficient (with all respect to Mr.
Knuth of course. For the kind of work he does, it probably makes a ton
of sense).
Not everyone agrees with that. I'm past the "Where do I start" step
and
routinely have problems understanding how to do what should be simple
tasks.
It's a logically untenable to say what I'm about to say, but I'm going
to say it. If you're still having lots of fits and false starts in
Rails, it is probably because you're not past that awkward first step.
But that aside, are you claiming that Rails needs more documentation?
It's allready one of the most well-documented projects anyone could
ask for. And while some people may not agree with it, it's undeniable
that many Ruby Nubys have come in and made meaningful patches to the
code. If that's not evidence of maintainability, I'm not sure what is.
Well, Barry. I can understand what you're saying, but....
The coders ARE the ones who can document the choice of algorithms
and explain why the function was written at all. I've had to
work on a lot of legacy, undocumented code and it is difficult.
It wastes more of my time that it would have taken the writer
to describe things well.
I can't help but believe that if a function's purpose isn't obvious
from reading it, then either the function is poorly written or the
reader has yet to grasp the domain. Code documentation can explain the
what, but it it shouldn't explain the why of things. The "why" can
change numerous times while the code remains the same.
There's nothing wrong with tech memos, design documents, and even
checking email logs. But the place for whys is not in the code. The
code is about hows and whats.
Is the original coder thinking of the maintainers? No, not
in this "me" generation. Not in this "obfuscated code"
generation ( hey, if you have trouble understanding this code
I wrote then you must not be as smart as I am! I win! )
I really don't think you can make any profound sociological
observations from observing the state of code written in the past at
your job. Unless of course you meant to attack me and the next
generation of coders personally. In which case, "1-2-3-4, I declare a
code war!"
Sy wrote:
>
> Just who would be writing and maintaining all that "commenting"
> anyways? The programmer is who.. so its style follows the
> programmer's mindset.. concise.. so they can move on to the next real
> issue --> more programming.
[...]
The coders ARE the ones who can document the choice of algorithms and
explain why the function was written at all. I've had to work on a lot
of legacy, undocumented code and it is difficult. It wastes more of my
time that it would have taken the writer to describe things well.
... "Yeahbut." I'd take a completely undocumented codebase
developed test-first, over the most lavishly documented
"traditional style" legacy codebase any day.
Not that I'm against useful comments. But have you ever
_seen_ what happens to code when developed test-first?
The result is small, testable routines that do one thing,
in a verifiable way, with minimal dependence on external
state.
So my point is that addressing the problem of obnoxious
untestable "ball of mud" style legacy code systems by
prescribing bundles of documentation to go with them. . .
is more like a band-aid on the problem, or treating the
symptoms rather than addressing the underlying.. eh,
illness.
Just $0.02
Regards,
Bill
From: "Barry Sperling" <barry@angleinc.com>