• (nodebb)

    // format the hard drives

    NuclearBomb.Launch();

  • (nodebb)
    1. Documenting WHY the code was written the way it was, is critical for mitigating the risk of lost tribal knowledge.
    2. The closer the documentation is to the item being documented, the higher the chance of it being maintained
    3. The code review process here failed horribly (and probably multiple times)
  • Tinkle (unregistered)

    Yep, the WTF is insisting on commenting every line - they should be as self-documenting as possible.

    To be fair, that comment is possibly highlighting a bug in the application - why has the timeout changed from 1 to 30 days?

    Having said that the comment is a little terse and not a lot of use in understanding what is being attempted at that point.

    Also, the comments should be updated before the code, as they should be viewed as part of the documentation (of the specification and how it is being achieved), rather than just stating what the code is doing.

  • Edd (unregistered)

    24rs? 24 hours, 24 seconds, or 24 of something?

  • Prime Mover (unregistered) 
    // Post frist comment
Comment.setOrdinalNumber(5)
  • Anonymous') OR 1=1; DROP TABLE wtf; -- (unregistered) in reply to Edd

    Maybe an 'r' is an obscure unit of time equal to 1.25 days

  • ooOOooGa (unregistered)

    Document 'why', not 'what'.

    And self-documenting code is a myth. If code could be understood just from reading the code, then computers could do our job. But understanding code just by reading code is a violation of Rice's Theorem.

  • (nodebb) in reply to ooOOooGa

    Understanding the WHAT is not a violation, (as mentioned previously) it is the WHY which represents the challenge. [NOTE: In addition to reading the code, one must have an understanding of the execution environment]

  • Well there ya go (unregistered)

    See how convenient it is to see that the comment is wrong, because it's right by the line of code? It would have been much harder to catch that documentation mistake had the comment been included in some document or paragraph at the top of the page.

  • Dlareg (unregistered) in reply to Anonymous') OR 1=1; DROP TABLE wtf; --

    r is not an obscure number. It is actually a speed. The speed you have to go without being late by in this case 24.

  • Twither (unregistered) in reply to ooOOooGa

    Obviously not all code can be self-documenting. Notably, code implementing complex algorithms where the result matters more than the method. That said, most code can and should strive to be self-documenting.

  • xtal256 (unregistered) in reply to ooOOooGa

    "If code could be understood just from reading the code"

    That is literally the entire point of high(er) level code though. It's why we no longer write in assembly language.

  • Donald Klopper (google) in reply to ooOOooGa

    Well put ooOOooGa

    Assuming that a higher level language or "higher level coding" (whatever that may mean) mitigate complexity is misguided.

    There is some truth to the language of domain vs language of design debate, but at the end of the day developers spend a lot of time in a language of design framework, which is most assuredly not self-documenting.

  • Christian Bau (unregistered)

    When I hear “self documenting code”: Sometimes it seems obvious that some code should be there, but there is a valid and less obvious reason why it isn’t. And code that isn’t there can’t document itself. It needs comments.

  • 516052 (unregistered)

    I don't understand how people can get so hung up on when and how to write comments. It's easy. Anyone who has ever had to write a paper on anything should have the instinctive undersatnding how to do it. Just think of your code as the main body of text and your comments as the footnotes.

  • The Shadow Knows (unregistered)

    So something else which can be traced back to "management" who have heard that comments are good, so decide comments for every line will be gooder.

  • eric bloedow (unregistered)

    several comments remind me of "dover cheetah" from an old comic "suburban jungle": "hello there." "set greeting="hello"." blink blink "so, you're a computer programmer?" "statement=true."

  • jay (unregistered)

    Anyone who says their code is self-documenting, tell me that again after you have to come back a year from now, figure it out and make a change.

    That said, what aggravates me the most is people who add documents to explain the things I could figure out from reading the code, and then don't bother to explain the things that are hard to figure out.

    Like I literally once came across a line of code that said:

    x=x+1; // Add 1 to x

    Like wow! Thanks for that helpful comment! I had forgotten what a plus sign does. But he gave no explanation of what "x" was or why he incremented it here.

Leave a comment on “Time Sensitive Comments”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article