Comment On Hyperverbosity

Ah. This looks very familiar.
It boggles my mind how the US Military can manage to do their extremely difficult job with Mission Planning software that stumbles over itself.

almost first :(

That looks like what happens when a CompSci major writes programs.

Hey! I'm a computer scientist and my code documentation is never that sparse. Remember, 95% documentation and 4% code with 1% variation for personal flare!


CAPTCHA: pirates -- arg!

Why -13? Simple, the programmer had used -1 to -12 in other places....

Could this be an excerpt of the documentation of a certain military flightsimulator?
http://worsethanfailure.com/Articles/Very,_Very_Well_Documented.aspx

OMG. I just HAVE to make a method in one of my classes that fits that description and copy/paste. Too good to pass up. ;)

Brett:

That looks like what happens when a CompSci major writes programs.

Explain why CS majors are thought to write more documentation than is necessary, because I am not aware of this stereotype.

OK, I'll be the apologetic voice here and trot out the old adage that documentation is like sex: when it's good, it's very good, and when it's bad it's still better than nothing.

Although nearly unreadable, certainly unmaintainable and lacking in Stuff That Matters, I would still prefer brain dumps like these over no documentation at all. They give insight in the twisted mind of the original developer, and such insights (while horrifying to the unprepared onlooker) can be a valuable aid.

Just don't rely on it to be correct. The source itself is the ultimate arbitrator. Well, the binary is, but the binary not matching the source is for another level of enlightenment.

Ugly and verbose, but this can actually be very useful. It is a LOT better than not having any comments, especially on such a hairy function.

It's possible that some guy had to maintain this code and had trouble with this function. So he explained (in painful detail) how this function works. Of course, the right fix would be to refactor the code but this is a lot harder than just commenting. It's likely that other parts of the code depend on the result being -13 (and not -12). In that case fixing this is really really hard.

I feel your pain.

I had a co-worker who wrote a very similar comment, although less useful, referencing "digital pencil" and "aliens"... all for a financial and inventory data structure.

Welbog:

Brett:

That looks like what happens when a CompSci major writes programs.

Explain why CS majors are thought to write more documentation than is necessary, because I am not aware of this stereotype.

I think the general idea is that computer students write a lot of extra documentation to "prove" to the grader that they know what the function does and didn't copy it from a friend. Also, since they're (typically) new to programming, they don't know what is and isn't useful and so put in more than they need. When I graded, I found this to be the case.

krupa:

Welbog:

Brett:

That looks like what happens when a CompSci major writes programs.

Explain why CS majors are thought to write more documentation than is necessary, because I am not aware of this stereotype.

I think the general idea is that computer students write a lot of extra documentation to "prove" to the grader that they know what the function does and didn't copy it from a friend. Also, since they're (typically) new to programming, they don't know what is and isn't useful and so put in more than they need. When I graded, I found this to be the case.

I don't recall ever doing that while obtaining my degree, nor do I recall anyone else doing it... However, I was not a grader and perhaps my peers and I were the abnormal ones...

I'm a comp sci graduate (and student), and I've also never heard of this stereotype. In fact, I think comments make code look ugly, and should be avoided at all costs. I also don't use variable names that are descriptive, but rather ones that are pleasing to the eye. It makes the code much prettier, and that's what is most important.

Koesper:

Could this be an excerpt of the documentation of a certain military flightsimulator?

Close, but not quite. This comment is from the GUI accompanying a program that does the AI and aeromodel for simulated air, ground, and naval targets. Said program and GUI are intended to be networked with flight simulators to provide a tactical training system.

JM:

OK, I'll be the apologetic voice here and trot out the old adage that documentation is like sex: when it's good, it's very good, and when it's bad it's still better than nothing.

Well, documentation that looks reliable but is in fact false, IS worse than none. Outright lies in the documentation can lead you on a false track, and instead of diving into the code to trace the bug, you seek it elsewhere because documentation says it will never behave the way it just does. Say, 'returns integer number of records found or NULL on error.' while it returns -1 on error and your if(!isNull($result)){ for($i=0;$i!=$result;$i++){...}} loop goes bananas.

I think a lot depends on a student's previous instructors and how much they stress comments. Some instructors don't care, others dock points for not having any.

That said, everyone is different and has their own style. When grading, I saw the range from no comments to "can't see the code through the comments."

IMHO, on a coding context, is better to writte list in a expanded way:

a) Foo the foo foo, fooo, foo. Belen.
b) Bar, bar, bar, baaa, bar. Ares.
c) Arrr, arr, ar, arrrr, arr. Railroad.

than this:

a) Foo the foo foo, fooo, foo. Belen.b) Bar, bar, bar, baaa, bar. res.c) Arrr, arr, ar, arrrr, arr. Railroad.

the 2th version need more eye effort, and the important data missed.
Most programmers seems that like the 1th version.

and write this:
case "a":
foo();
break;
case "b":
bar();
break;
case "c":
arr();
break;
instead of this:
case "a": foo();break;case "b":bar();break;case "c":arr();break;

you can make a long text readable with whitespaces on tactical locations.

krupa:

That said, everyone is different and has their own style. When grading, I saw the range from no comments to "can't see the code through the comments."

Is there an average or anything? As in, were the majority of submissions comment-laced or were they comment-lacking? I'm assuming that there is a standard normal curve of "number of lines of comment per line of code", but where does the average lie for students you've graded?

Geez, you guys get on me for not writing comments, now you're on me for writing comments. Make up your mind :)

kramthegram:

...with 1% variation for personal flare!

Do you spontaneously combust?

Andy Goth:

Close, but not quite. This comment is from the GUI accompanying a program that does the AI and aeromodel for simulated air, ground, and naval targets. Said program and GUI are intended to be networked with flight simulators to provide a tactical training system.

Is it OTBSAF? I recall seeing some pretty horrible comments when using that application years ago...

Crabs:

I'm a comp sci graduate (and student), and I've also never heard of this stereotype. In fact, I think comments make code look ugly, and should be avoided at all costs. I also don't use variable names that are descriptive, but rather ones that are pleasing to the eye. It makes the code much prettier, and that's what is most important.

Amen! Now that's true Computer Science!

My code doesn't need comments anyway, it's always self-documenting. I sometimes comment other people's code, although it's usually something like:

// WTF?

Maybe. Or perhaps it's just another way of saying EACCES.

Welbog:

krupa:

That said, everyone is different and has their own style. When grading, I saw the range from no comments to "can't see the code through the comments."

Is there an average or anything? As in, were the majority of submissions comment-laced or were they comment-lacking? I'm assuming that there is a standard normal curve of "number of lines of comment per line of code", but where does the average lie for students you've graded?

I really couldn't tell you at this point; it's been a few years. I'm kind of guessing here, but I'd say the majority had more comments, again because students wanted to prove they knew what their code did.

s.:

Well, documentation that looks reliable but is in fact false, IS worse than none. Outright lies in the documentation can lead you on a false track

I'm with you 100% on this.

A missing handrail is safer than a rickety one, because if there's no handrail you keep way from the edge.

s.:

JM:

OK, I'll be the apologetic voice here and trot out the old adage that documentation is like sex: when it's good, it's very good, and when it's bad it's still better than nothing.

Well, documentation that looks reliable but is in fact false, IS worse than none. Outright lies in the documentation can lead you on a false track, and instead of diving into the code to trace the bug, you seek it elsewhere because documentation says it will never behave the way it just does. Say, 'returns integer number of records found or NULL on error.' while it returns -1 on error and your if(!isNull($result)){ for($i=0;$i!=$result;$i++){...}} loop goes bananas.

That's partly why you should use <,>,<=,>= instead of !=. If you used $i<$result then it would skip the loop when the result turned out to be -1.
Of course, this could still be bad, but better than an infinite loop.

I know this commenting style well, and it can be summed up in four words: "Way too much Adderal."

Actually, the two's complement integer representation of -13 on a system almost corresponds to an ascii question mark.


-13 -> -(0000 1101) -> 1111 0010 + 1 -> 1111 0011 -> F3

Switch the byte halves, and you have 3F. So the real WTF is that the programmer can't use an ASCII table.

:)

~Sticky

/And no, this has nothing to do with endian representation, so don't embarrass yourself

This represents a very old division of labor, wherein "analysts" programmed in highly detailed technical prose like this, essentially what needed to be done point-for-point, and then "coders" translated it into whatever mysterious notation (typically assembly language of some sort) the computer du jour required to represent that intent. It doesn't astonish me that the military would keep up such a style long after the rest of the computing world had merged the two functions.

The word "Description:" very much suggests that this text was cut'n'pasted from a larger "analyst" document containing blow-by-blows for hundreds or thousands of these procedures.

Reminds me of a manager that wanted to see a comment on every line, so I wrote a little Perl program that would add a comment on each line, something guessed from the line, such as

"// compare i and max"
"// if greater, set i to max"
"// else print "values out of sequence""

Hmm, the number 13 is unlucky - so surely the number -13 is lucky? So the number 13i probably represents wishful thinking. Which means -13i is ... *brain melts*

Bosshog:

Hmm, the number 13 is unlucky - so surely the number -13 is lucky? So the number 13i probably represents wishful thinking. Which means -13i is ... *brain melts*

Wishless thinking?

Hognoxious:

s.:

Well, documentation that looks reliable but is in fact false, IS worse than none. Outright lies in the documentation can lead you on a false track

I'm with you 100% on this.

A missing handrail is safer than a rickety one, because if there's no handrail you keep way from the edge.

That really depends.... if the precipice is obvious and visible, then yes - if it's hidden, like a missing manhole cover, any form of visual cue is better than none. On top of that, if the handrail _looks_ rickety, no one would try to lean on it anyway.

So how does that translate to code - if you are going to write long, detailed and verbose documentation (a solid-looking handrail), you'd better be certain that the code is set in stone (like e.g. Sun's Java APIs). If the code doesn't have a well defined interface, and/or its implementation is likely to change a lot, you're better off with small inline comments instead.

To the guy who says comments detract from the beauty of the code: I really hope you limit your work to ASCII art, because the rest of us are coding _real_ applications, that involve a lot of detail, context, gotchas and other stuff that _needs_ to be documented, or else everyone after will spend days or weeks trying to work it out.

I oince inherited a system that, like most, had a few routines that did most of the work. Naturally, the central routine was thousands of lines of single character variables, hard-coded constants, ems-queues in and out, callbacks, and so forth. Finally, I had had it, and put comments like the following all over the place, and kept them up to date, so you could see what was actually happening at a glance:

//   +--------+                    +--------+                   +--------+

//   | Task-1 |  --> TIB-EMS-1 --> | Task-2 | --> TIB-EMS-2 --> | Task-3 |

//   +--------+                    +--------+                   +--------+

//                                                                  |

//                                                                  | TIB-EMS-3

//                                                                  V

//   +--------+                    +--------+                   +--------+

//   | Task-6 |  <-- TIB-EMS-5 <-- | Task-5 | <-- TIB-EMS-4 <-- | Task-4 |

//   +--------+                    +--------+                   +--------+

//       |

//       | TIB-EMS-6

//       V

//      <and so on>

I remember working with someone who was a little "special", to say the least.
He wrote this God-ugly method which was impossible to decipher and had no comments or documentation. He was asked during code review to tidy it up and add comments.
Months later I came across the same method and he had left the method as is and added one comment, just above the method definition:

// This method is the devil's testicle

So the WTF is that people actually bother to read someone else's comments, especially ones that long, without their eyes glazing over?

Or is it that they didn't wrap -13 in a constant?

Maybe both?

"Incorrect documentation is often worse than no documentation." -Bertrand Meyer

At least he understands that datum is singular.

Welbog:

Brett:

That looks like what happens when a CompSci major writes programs.

Explain why CS majors are thought to write more documentation than is necessary, because I am not aware of this stereotype.

Maybe because CS majors are hoping that someone else will have to maintain their code while they go on to bigger and better things.

I was working on something one day when an engineer who worked for one of the NASA contractors stopped by the office. He looked over my shoulder and said that I had way too many comments. I don't remember his exact words, but the impression I got was that he didn't use any comments, ever.

I bet you can guess which of us wrote code that someone else could pick up and figure up what it did.

Detective Dolly: So what's the symbology there?

Paul Smecker: Well, now that Duffy has relinquished his "King Bonehead" crown I see we have an heir to the throne! I believe the word you were looking for is "symbolism." What is the ssss-himbolism.

michael:

To the guy who says comments detract from the beauty of the code: I really hope you limit your work to ASCII art, because the rest of us are coding _real_ applications, that involve a lot of detail, context, gotchas and other stuff that _needs_ to be documented, or else everyone after will spend days or weeks trying to work it out.

One of these days, I'll go ahead and teach you how to understand sarcasm.

However, and I'm not joking here, too many comments can make code unreadable. A descriptive method name, intuitive variable names, and a few inline comments around confusing areas is more than sufficient in just about every case. Obvious code trumps heavily commented code every time, and obvious code really isn't any harder to write. If your code needs heavy comments to be understandable, Occam's razor would suggest there is an easier way.

Welbog:

Brett:

That looks like what happens when a CompSci major writes programs.

Explain why CS majors are thought to write more documentation than is necessary, because I am not aware of this stereotype.

That stereotype must be spread somewhat, as I've recently heard from my Sci Comp professor that students with CS background submit very long, profusely documented programs for their problem solutions. I usually do it in a page or two of self-documenting C++ source with nary a comment; it's self documenting (I mean it).

Cheers!

StickyWidget:

So the real WTF is that the programmer can't use an ASCII table.

:)

~Sticky

I'll bet he can use a WOODEN table, though!

John Cowan:

This represents a very old division of labor, wherein "analysts" programmed in highly detailed technical prose like this, essentially what needed to be done point-for-point, and then "coders" translated it into whatever mysterious notation (typically assembly language of some sort) the computer du jour required to represent that intent. It doesn't astonish me that the military would keep up such a style long after the rest of the computing world had merged the two functions.

The word "Description:" very much suggests that this text was cut'n'pasted from a larger "analyst" document containing blow-by-blows for hundreds or thousands of these procedures.

Thanks, that explanation makes sense. I would, however, split the comment into three parts: Description, Input Parameters, and Output.

Crabs:

However, and I'm not joking here, too many comments can make code unreadable. A descriptive method name, intuitive variable names, and a few inline comments around confusing areas is more than sufficient in just about every case. Obvious code trumps heavily commented code every time, and obvious code really isn't any harder to write. If your code needs heavy comments to be understandable, Occam's razor would suggest there is an easier way.

Hear! Hear!

To the uninitiated, that code probably looks remarkably like a C function. But looks can be deceiving. Fortunately, the original programmer added a comment to point out that this is actually an implementation of a C function, not the C function itself, which is presumably a Platonic ideal that can never exist in the real world. The advantage of this is obvious -- it allows one to easily replace the function's implementation with a different one simply by changing the source code.

It's not often that you see the work of a programmer capable of providing an additional level of abstraction entirely in comments. This is genius.

Beginners comment nothing.
Novices comment the obvious.
Journeymen comment why they did it.
Masters comment why they didn't do it differently.

synic:

I had a co-worker who wrote a very similar comment, although less useful, referencing "digital pencil" and "aliens"... all for a financial and inventory data structure.

"The Real WTF" (tm) is that you haven't submitted that to WorseThanFailure.com!

kindall:

...this is actually an implementation of a C function, not the C function itself, which is presumably a Platonic ideal that can never exist in the real world. The advantage of this is obvious -- it allows one to easily replace the function's implementation with a different one simply by changing the source code.

This is the funniest thing I have read for weeks (and I read Scott Adam's blog). Thank you, thank you for a liberal-arts geek joke.