• Jon W (unregistered)

    "Oh, my God, we forgot to comment the code!"

    "Don't worry, we'll have the Indian Outsourcing company read each function and describe it."

    I've found that writing good documentation doesn't come naturally to a lot of people. Especially people who haven't written real programs using real API documentation across a range of platforms/APIs. You have to have a certain kind of creativity to imagine what a user of a function would actually need to know, if he didn't already have the knowledge that you have yourself about the system. Then you need to make sure the function documentation actually provides that information, in a consistent and readable manner.

    It's a skill you have to practice, and it requires as much creative writing skills as it requires coding skills. Not all (or even most) programmers are that great at creative writing.

  • Greg (unregistered)

    Its pretty scary a single function could do all that.

  • sammy (unregistered) in reply to Brett
    Brett:
    That looks like what happens when a CompSci major writes programs.

    I was a comp sci major. I hate to say it, but I had a professor who wanted us to write comments about as verbose as this one. He was uniformly detested by his students, and he was terrible at grading work promptly.

    In fact - the first of five assignments I turned in to him for my Data Structures class was returned to me on the last day of class, after the fifth assignment had been turned in as well. I'd had numerous points deducted because my comments... well, because they didn't look like this.

    Of course, they still don't, so. Nyah.

  • Elizabeth Jane (unregistered)

    ...err...um ...that '-13'??? Would that be in hexadecimal?

  • Brett (unregistered)

    Back in my day, CompSci majors/graduates didn't write programs. They wrote definitions for lexical parsing systems that were impractical, obtuse, and yet impressive. The stereotype is CompSci majors vs. world-weary programmers who have to try and implement such faerie castles, much like the stereotype of Electrical Engineers vs world-weary electronic technicians who have to hammer all of the bugs out of the design because the real world was never actually taken into account by the design engineers.

    There, is there anybody left I've failed to irritate? I was born a couple years too late to qualify to be an "undegreed engineer", so even though I've been in the business for 30+ years and know computers from the electron hole theory of silicon solid-state semicondutors through operating system implementation and on through database design and user interfaces (by doing it), I never got a degree and harbor a natural skepticism of people who seem unduly proud of theirs. To me, PhD stands for "Piled higher and Deeper".

    Back in my day, hard drives were the size of pizzas and held 5 megabytes.

  • Robert S. Robbins (unregistered)

    Comments are for the programmer that has to maintain your application six months from now. That poor soul will probably be you.

    I don't think comments alone really cut it. I often need screen captures to help me find things. I create help collections for my major projects and then integrate them into the MSDN Library. I also print out my database schema so I don't need to fire up SQL Server just to get a column name.

    You can create Class Diagrams using UML in Visual Studio but I don't use that often enough. Tracepoints have proven to be quite useful to me when a stack trace can't be used to document the method calls during execution. You should also instrument your code with trace listeners.

    I won't even mention the videos.

  • (cs) in reply to Ancient_Hacker
    Ancient_Hacker:
    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""

    Genius! Why don't you dig out the code and open-source it?

  • (cs) in reply to taylonr
    taylonr:
    Geez, you guys get on me for not writing comments, now you're on me for writing comments. Make up your mind :)

    It's The Adams Rule of Work-Related Horror Stories: any story about one or more horrible coworker who have a horrifying habit of doing non-criminal act X can be retold with a change in narration as a story about one or more horrible coworkers who have a horrifying habit of neglecting to do X, and both stories will seem perfectly reasonable as long as they are not directly juxtaposed. This rule is named after Scott Adams not because he discovered it -- he may or may not even be aware of it -- but because a close reading of Dilbert cartoon strips reveals that he has told the same story from both sides several times.

  • (cs) in reply to The Vicar

    This is like the documentation-equivalent of computer-generated code. If someone wrote a compiler that could actually generate documentation for a function by looking at its code, this is what it would look like.

  • (cs) in reply to Jon W
    Jon W:
    It's a skill you have to practice, and it requires as much creative writing skills as it requires coding skills. Not all (or even most) degreed programmers are that great at creative writing.

    There fixed that for you. Us old timers that have been doing this for years for some reason seem to be ex musicians. I have always been able to put together impromptu jam sessions simply from the rest of the team around me. Now that shows we have the creativity.

  • (cs) in reply to Crabs
    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.
    Add to that API documentation at the method and class level (not always, but often), and I'm with you 100%. The user of a class or method shouldn't have to look at the code to understand what it does and how to use it, and names often cannot (and should not) be descriptive enough. One of the major assets of the Java language is the ubiquitous Javadoc standard for API documentation.
  • AnnC (unregistered) in reply to DaveK
    DaveK:
    Ancient_Hacker:
    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""

    Genius! Why don't you dig out the code and open-source it?

    I've seen the code and I don't quite understand it. Can you add some comments?

  • el jaybird (unregistered) in reply to John Cowan
    John Cowan:
    TThe 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.

    Yep, I started reading the comment block and started thinking this looked like a list out of a requirements document or a DOORS database or some such, and the programmer was perhaps keeping the comments verbatim for requirements tracability.

    This is what I deal with, working in the defense contracting industry.

  • Steve (unregistered)

    Actually, the writing style reminds me more of some electrical engineers I've worked with than CS majors.

  • (cs) in reply to richardchaven
    richardchaven:
    Beginners comment nothing. Novices comment the obvious. Journeymen comment why they did it. Masters comment why they didn't do it differently.

    I'll drink to that.

  • Unenlightened as well (unregistered)

    Is that documentation, or an actual COBOL program?

  • mtu (unregistered)

    The function operates on the presumption that these parameters are valid.

    Can anyone think of a snobbier way of saying "Input must be correct", "No error handling here" or "Don't pass bullshit!"?

    CAPTCHA: waffles. Yum!

  • captain obvious (unregistered) in reply to richardchaven
    richardchaven:
    Beginners comment nothing. Novices comment the obvious. Journeymen comment why they did it. Masters comment why they didn't do it differently.
    Masters shut the fuck up and do the job.
  • benjee (unregistered)

    What i like most about this post,

    // initializing three particular ex	ternal structure elements with arrays of

    the authore seemed to have tried to emulate block text with his texteditor. but id didn't quitet work out as it should had;)

  • Andy Goth (unregistered) in reply to Greg
    Greg:
    Its pretty scary a single function could do all that.
    What, initialize three fields in a structure with data it got out of a file? Yeah, I smell your sarcasm, but to be perfectly honest, the sheer size of the comment does indeed make it look like the function must be all-powerful. Excuse me. I meant to say: the comment makes the *implementation* of the function seem all-powerful!
  • Rich (unregistered) in reply to AnnC

    "sure, let me just..." universe implodes

  • Rich (unregistered) in reply to AnnC

    (Sorry, I accidently hit 'reply' instead of 'quote')

    AnnC:
    DaveK:
    Ancient_Hacker:
    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""

    Genius! Why don't you dig out the code and open-source it?

    I've seen the code and I don't quite understand it. Can you add some comments?

    "sure, let me just apply my..." universe implodes

  • (cs) in reply to ParkinT

    No, -13 is just his way of saying "Hey, I don't know that unsigned data types can't take negative values!"

    Chars can take negative values. Bytes are, by definition, unsigned, so the doofus is obviously not playing with a full deck on this one.

  • boyd (unregistered) in reply to Thief^
    Thief^:
    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?

    Nightmare.

  • Kunal (unregistered)

    Now the software engineers should learn from this guy on how to write comments!

    WTF!

  • (cs) in reply to richardchaven
    richardchaven:
    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.

    Quite welcome. Glad someone enjoyed it.

  • (cs)

    Another Knuth knut - see the example in Appendix A. And note the title at the top of page 12.

    Addendum (2007-11-29 07:30): And this.

  • Anon (unregistered) in reply to mrprogguy

    Since when do chars take negative values? What character is -1?

  • (cs) in reply to John Cowan
    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.
    I was once in a project with such documentation (over ten pages for just the CRUD operations on a database table). It took some weeks until I was able to switch off my brain and begin typing word-for-word what read in the documentation. Fortunately the project was discontinued. That was some of the worst code I've ever written - probably even worse than in my very first programs.
  • (cs) in reply to Anon
    Anon:
    Since when do chars take negative values? What character is -1?

    There are signed chars and there are unsigned chars. Signed chars can take negative values, although I'm not sure why one would want to.

    The plain char is either a signed char or an unsigned char, but which one it is depends on your implementation.

  • (cs) in reply to The Vicar
    The Vicar:
    -- but because a close reading of Dilbert cartoon strips reveals that he has told the same story from both sides several times.
    He started the strip April 16th, 1989 (according to Wikipedia). Allowing one strip per day since then, he's drawn 6,802 of them. It's understandable that he likely would revisit a theme in there from time to time.
  • hobart (unregistered) in reply to Ancient_Hacker
    Ancient_Hacker:
    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""

    He would have been far better telling you not to use things like "i" as variable names.
  • MycroftMkIV (unregistered) in reply to JM
    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.

    I guess I have to dispute the latter part of that statement.

    Many years ago, I worked with a guy who did an assembly language program to help test a realtime system. He did not put a single comment in the code and our boss dinged him big time, since the code was not maintainable. So he wrote comments on EACH line of the code, with statements like

    LDA A W[1234] LSH L 1

    becoming

    LDA A W[1234] ; Load accumulator with contents of 1234 LSH L 1 ; Shift acc left by one bit.

    This guy ended up at a mental hospital and I was the unfortunate recipient of all his work.

  • (cs) in reply to KattMan
    KattMan:
    Us old timers that have been doing this for years for some reason seem to be ex musicians. I have always been able to put together impromptu jam sessions simply from the rest of the team around me.
    True that. Our team has often performed musically for the rest of the department at Christmastime, and a couple of years back we had two developers who had BA's in music.
  • Ubersoldat (unregistered) in reply to Crabs
    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.

    He! I also hate comments, instead I insert a .bmp file with a flowchart.

    Bathe... no I won't... too many BMP's to convert to ASCII!

  • Troy (unregistered) in reply to Brett

    One wonders what your degree is in.... Having a BSCS for Purdue and having written a few million lines of code in the last 20 years, I would be happy to compare abilities....

  • (cs)

    What irks me is the apparent misuse of "id est". I'm very sure that what the author of this pretentiously moronic documentation comment was looking for is "exampla grata".

  • Dave (unregistered) in reply to Someone You Know

    The plain char is either a signed char or an unsigned char, but which one it is depends on your implementation.

    There's also just plain 'char', a distinct type.

    BTW: I don't know what the problem is with the comment this article is about. Too much comment is better than no comment at all...isn't it? No-one's forcing you to read it, but it's there if you want to.

  • Marco A. (unregistered)

    Other WTF is that he could have used a Multi-line comment, but instead he used 17 single line comments

  • M L (unregistered) in reply to John Cowan
    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.

    I was thinking the same thing, actually. The oddball space in the word "external" really points it out to be a c'n'p.

  • Andy Goth (unregistered) in reply to M L
    M L:
    The oddball space in the word "external" really points it out to be a c'n'p.
    This was most definitely cut'n'paste. All the other functions used the same verbiage with a few minor modifications. You may not have noticed, but the "Description:" line seems to have been "tuned" to fill the line exactly, so that the original coder could copy it directly without having to make edits in the middle of the line.

    At one point the other awkward boilerplate phrases ("The function operates on the presumption that these parameters are valid.") were probably on their own line(s) too, but over time they must have been re-flowed within the paragraph.

    Exhibit A: not counting //'s, the number of characters in the "Description:" line (73) is exactly equal to the number of characters in the "presumption" sentence.

    Actually I'm not sure the "external" spacing was part of the original; Alex may have introduced it. But I can't say for certain either way. Whatever, it's funny. :^)

  • JudgeDread (unregistered)

    ...better than no documentation.

    On my last job I took over a project (C++) which had been jointly developed with another company and in which my company had just bought out all rights. When the source code was delivered it did not have one comment anywhere (50,000 line of code). I assume that out of badness they passed it through some utility to strip out all comments. Sorry, there was one comment left in each file, the name of the original programmer at the top. Not only was it missing all the comments, it was so badly written I was surprised he put his name to it. A big rewrite was in order. In two days I managed to get rid of 10,000 lines of code. By the end of the second week I had halved the number of lines of code and lopped a third of the final binary.

  • Synonymous Awkward (unregistered) in reply to Dave
    Dave:
    > The plain char is either a signed char or an unsigned char, > but which one it is depends on your implementation.

    There's also just plain 'char', a distinct type.

    Which is, presumably, neither signed nor unsigned.
  • Jay (unregistered)

    well that clearly indicates that the function is a authenticator of the validity of the symbology modifiers being presented. The -13 would indicate that a previous -12,-11,-10... were already allocated to other functions as fail indicators forcing this functions need to be unique as a -13. Most likely the calling of the function would try for a positive number of zero and use the -13 number to look up the appropriate message to display back to the source of input which started the entire process in the first place. This is a very good way to document black box programs.

  • ELIZA (unregistered) in reply to richardchaven
    richardchaven:
    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.

    It is not that much of a joke. The words actually make sense in some context, for example in an implementation of the C standard library: As far as I know, most language specifications simply define the behaviour of functions, so that a C function itself is an "oracle", eg, you call Sqrt(10000) and it returns 100, but the specifications do not tell1 you how Sqrt(x) is actually implemented (my choice would be result=exp(log(x)/2), but it could also be iterated guessing or any number of ways I have not thought of, as long as it has the specified performance).

  • Oduvan4ikRaft (unregistered)

Leave a comment on “Hyperverbosity ”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article