• mav (unregistered)

    So anyways, in my mind pointless comments are worse than no comments at all. Except maybe pointless comments where good comments should be...

    CAPTCHA: "pointer" as in,

    // lookit me! i'm a 4 star programmer! char ****buf;

  • (cs)

    // TODO: Add meaningful comment here

  • (cs)

    The comments aren't the only thing bad about the second piece. It confuses the concepts of stacks and queues. If the item is going on the front and coming off the back, the proper function names should be enqueue and dequeue.

    Also, pop and dequeue operations usually return the value to the caller. (or null if the list is empty)

  • (cs)

    I once had a kollegue that left me code with comments like

    //i should write a comment here //i'm so lazy or //total useless code

    that didn't increase the readability

  • (cs)

    I get my jollies by leaving intentionally misleading comments. It's almost as much fun as misnaming variables.

  • (cs)

    Oh.. and those Hex comments are probably because most people don't know how to take the hex notation from most C/C++/C# examples and convert them to VB hex, so they get the matching long/integer value and use that for a Const. The comment is so anyone who comes along can see the matching hex value that everyone else is using in code.

    I used to have to support a DOS-based EDI system written in Clipper. The element and segment separators were entered in as hex. Even the trading partners and VANs told the separators in hex. However, in VB, people tend to only know the ASC value, which is an Int. By including the comment, if anyone mentions the hex, or asks you which hex you are using, the comment will tell you instead of having to calculate it elsewhere.

  • (cs) in reply to akatherder
    akatherder:
    I get my jollies by leaving intentionally misleading comments. It's almost as much fun as misnaming variables.

    That's especially fun if you don't particularly like the person who's looking at it. We've got a boss (in another office) that insists on seeing everything we do even though he doesn't have a clue about the languages (they only know Java in that office and can't comprehend anything else).

  • (cs)

    The second example looks like its implementing a stack interface to a queue data structure? So you push Z, then pop the stack expecting to get Z back, but instead you get A.

    Derrick, you're right on the money about WTF sources: most of the WTFs come from the comments right here. You should start posting code snippets that are actually good code, just to see how many people will crap on it and invent wild theories about what could possibly be wrong with it.

  • C++ Coder (unregistered) in reply to notromda
    notromda:
    The comments aren't the only thing bad about the second piece. It confuses the concepts of stacks and queues. If the item is going on the front and coming off the back, the proper function names should be enqueue and dequeue.
    Why should the interface method names reflect the internal data structure? Actually, a name that hides the internal implementation is way better.
    notromda:
    Also, pop and dequeue operations usually return the value to the caller. (or null if the list is empty)
    The code is C++. In C++ the standard containers DON'T return the value poped for exception safety reasons. There are numerous explanations of this design decision to be found on the web.
  • (cs)

    The hex one has good reasons, for example ease of grepping.

    As for the second one: it always helps to explain what a function is intended to do, especially when you give them the entirely wrong name :)

  • (cs) in reply to AbbydonKrafts
    AbbydonKrafts:
    I used to have to support a DOS-based EDI system written in Clipper.

    Yaaaay! Clipper! Yaaaaay!!!

    I loved Clipper back in the day.

    Not so much anymore.

  • (cs) in reply to C++ Coder
    C++ Coder:
    notromda:
    The comments aren't the only thing bad about the second piece. It confuses the concepts of stacks and queues. If the item is going on the front and coming off the back, the proper function names should be enqueue and dequeue.
    Why should the interface method names reflect the internal data structure? Actually, a name that hides the internal implementation is way better.

    But pop/push and queue/dequeue aren't implementation details, they're interface details. There are lots of ways you can implement a stack or a queue, but it's still important that the user know which one they're dealing with.

  • (cs) in reply to skztr

    As seen in http://seenonslash.com/

    /* And so forth have come the greatest minds of the universe and they have contsrutcted the machine of might that we know as computer. At first to harness the insurmountable power of the Computer, one had to know its language of the lowest levels. Generations that have come afterwards, however, invented many other tongues in which to speak to the machine, some of them of levels higher than before. And then Goslin, a man of the Machine, started one of such tongues, called Java. It then became one of the most widely used tongues in which the masters of the machine spoke to it. Many of them can force the machine to speak back to them, using the almighty terminal, where the machine places forth letters arranging them into words so that we might see the Machine's great wisdom. Even the least powerful of the mighty masters of the machine therefore know the very basic words, that the machine needs to receive in order to go forth and greet all of those that would seek its audience. These mighty words of wisdom and power to are: */

    System.out.println("Hello, World!"); // Prints Hello, World!

  • axl (unregistered) in reply to skztr

    The comments are also technically wrong, since push_back adds to the end and pop_front removes from the head.

  • Look at me! I'm on the internets! (unregistered) in reply to notromda
    notromda:
    The comments aren't the only thing bad about the second piece. It confuses the concepts of stacks and queues. If the item is going on the front and coming off the back, the proper function names should be enqueue and dequeue.

    Also, pop and dequeue operations usually return the value to the caller. (or null if the list is empty)

    Notwithstanding the method names (wtf?), I'm going to guess that there's probably a peek() method that returns the value and leaves it on the queuestack.

  • clif (unregistered)

    I had a manager who was also a great programmer. However when she told other developers to make changes to their code they would add her name in the comments and nothing else. It drove her nuts. Another favorite comment was the programmers initials and date. How useless is that.

  • Look at me! I'm on the internets! (unregistered) in reply to axl
    axl:
    The comments are also technically wrong, since push_back adds to the end and pop_front removes from the head.

    Fark you and your imposition of directionality on my design. I prefer to think about it in the other direction.

  • Look at me! I'm on the internets! (unregistered) in reply to clif
    clif:
    I had a manager who was also a great programmer. However when she told other developers to make changes to their code they would add her name in the comments and nothing else. It drove her nuts. Another favorite comment was the programmers initials and date. How useless is that.

    At least we know who to blame.

  • steve (unregistered) in reply to EnterUserNameHere
    EnterUserNameHere:
    AbbydonKrafts:
    I used to have to support a DOS-based EDI system written in Clipper.

    Yaaaay! Clipper! Yaaaaay!!!

    I loved Clipper back in the day.

    Not so much anymore.

    I hated that sumbitch! Always thought he was so smart.

  • Jens (unregistered) in reply to clif
    clif:
    I had a manager who was also a great programmer. However when she told other developers to make changes to their code they would add her name in the comments and nothing else. It drove her nuts. Another favorite comment was the programmers initials and date. How useless is that.

    Ever heard of grep... I find it very usefull to be able to find all changes made by a certain programmer on a specific date.

  • Misha (unregistered) in reply to Look at me! I'm on the internets!
    Look at me! I'm on the internets!:
    clif:
    I had a manager who was also a great programmer. However when she told other developers to make changes to their code they would add her name in the comments and nothing else. It drove her nuts. Another favorite comment was the programmers initials and date. How useless is that.

    At least we know who to blame.

    $ svn blame wtf.c

  • Dark Shikari (unregistered) in reply to akatherder
    akatherder:
    I get my jollies by leaving intentionally misleading comments. It's almost as much fun as misnaming variables.

    Try something like this sometime then:

    if(do_loop){
array[0]=x;
array[1]=x+1;
array[2]=x+2; /* Unroll loop to
array[3]=x+3;    increase speed
array[4]=x+4;    since compiler
array[5]=x+5;    doesn't have
array[6]=x+6;    loop unrolling */
array[7]=x+7;
}

    The program's maintainers will love you for it.

  • DavidJ (unregistered) in reply to axl

    The first set of comments might have been helpful if the Hex values corresponded to a code table (and the coder didn't know how to enter Hex values).

    I think the second commentor misunderstood what pop_front() was doing... he (she?) noticed the last element "disappeared" every time pop_front() ran.

    Captcha: howdy (as in... I just started reading WorseThanFailure last week and this is my first comment :-) )

  • C++ Coder (unregistered) in reply to SuperousOxide
    SuperousOxide:
    C++ Coder:
    notromda:
    The comments aren't the only thing bad about the second piece. It confuses the concepts of stacks and queues. If the item is going on the front and coming off the back, the proper function names should be enqueue and dequeue.
    Why should the interface method names reflect the internal data structure? Actually, a name that hides the internal implementation is way better.

    But pop/push and queue/dequeue aren't implementation details, they're interface details. There are lots of ways you can implement a stack or a queue, but it's still important that the user know which one they're dealing with.

    But the client doesn't need to know that the operations push and pop really correspond to push and pop of the internal data structure. You can have the internal data structure implemented backwards for whatever reason as long as the interface is consistent with itself. As far as I can see, there is nothing inconsistent at the interface level.

  • dp.design (unregistered)

    // now I just need to get something off the array // hmmmmmmmm!!!!!

  • Bob P (unregistered)

    I used to use something like:

    int IDontKnow; //Self documenting variable int IDontCare; //Self documenting variable

    As fillers in structures that were (ill)defined in other parts of the system.

  • Mike5 (unregistered) in reply to Dark Shikari
    Dark Shikari:
    akatherder:
    I get my jollies by leaving intentionally misleading comments. It's almost as much fun as misnaming variables.

    Try something like this sometime then:

    if(do_loop){
array[0]=x;
array[1]=x+1;
array[2]=x+2; /* Unroll loop to
array[3]=x+3;    increase speed
array[4]=x+4;    since compiler
array[5]=x+5;    doesn't have
array[6]=x+6;    loop unrolling */
array[7]=x+7;
}

    The program's maintainers will love you for it.

    Especially since lines 3, 4, 5 and 6 are commented out.

    Mike5

  • gerrr (unregistered) in reply to C++ Coder
    C++ Coder:
    SuperousOxide:
    C++ Coder:
    notromda:
    The comments aren't the only thing bad about the second piece. It confuses the concepts of stacks and queues. If the item is going on the front and coming off the back, the proper function names should be enqueue and dequeue.
    Why should the interface method names reflect the internal data structure? Actually, a name that hides the internal implementation is way better.

    But pop/push and queue/dequeue aren't implementation details, they're interface details. There are lots of ways you can implement a stack or a queue, but it's still important that the user know which one they're dealing with.

    But the client doesn't need to know that the operations push and pop really correspond to push and pop of the internal data structure. You can have the internal data structure implemented backwards for whatever reason as long as the interface is consistent with itself. As far as I can see, there is nothing inconsistent at the interface level.

    The interface misleads the users as to its behavior, not about it's implementation.

    Push and pop mean you are using a stack. If I push something then I expect to get it when I call pop. I do not expect to get the first thing I pushed.

    Naming functions push and pop when the behavior is a queue is stupid wtf'ery.

  • Former Jr. Programmer (unregistered)

    // TODO: Comment

  • Sauron (unregistered) in reply to notromda
    notromda:
    The comments aren't the only thing bad about the second piece. It confuses the concepts of stacks and queues. If the item is going on the front and coming off the back, the proper function names should be enqueue and dequeue.

    I don't know. To me that snippet screams "DEQUE!". Granted, the use of the functions push and pop where one would expect enqueue and dequeue may be a misunderstanding of stack/queue structure, I would think it far more possible to be an attempt at consistency with the deque's own function names (in C).

    Or I might be trying to hard to give them the benefit of the doubt....

  • (cs) in reply to savar

    At least the hex values are right. It'd be so much fun to change just a few of the decimal values just a bit each :)

    And:

    savar:
    Derrick, you're right on the money about WTF sources: most of the WTFs come from the comments right here. You should start posting code snippets that are actually good code, just to see how many people will crap on it and invent wild theories about what could possibly be wrong with it.

    Isn't he already doing it for a time now? I can remember a few WTFs that weren't.

  • (cs)

    Albeit having a backwards internal representation, the push/pop implementation would work like a charm :) It's just like when you're driving with right-hand steering in Britain and you look in your rear-view mirror to read the "ecnalubmA" on the van behind you. Or something.

  • LintMan (unregistered)

    The first set of comments isn't necessarily bad - I've seen similar and found them useful.

    Possible scenario: The values used are being supplied from a spec that provides them as decimal. It is desirable to be able to verify the constant values in the source directly against those listed in the spec without having to do the decimal/hex conversion on the fly or create a new spec table with hex values.

    But, perhaps you are dealing with buffer packing or other byte manipulation, and when looking at the data, hex might be more convenient to work with. Having the hex conversion right there in the comment saves some effort.

    Of course, it does make for the possibility that some bozo will change the values but not update the comments, but they probably won't change often and they're side by side, so it's not that likely to happen, and it's a fairly easy catch if it did.

  • Jeff T (unregistered) in reply to Dark Shikari
    Dark Shikari:
    akatherder:
    I get my jollies by leaving intentionally misleading comments. It's almost as much fun as misnaming variables.

    Try something like this sometime then:

    if(do_loop){
array[0]=x;
array[1]=x+1;
array[2]=x+2; /* Unroll loop to
array[3]=x+3;    increase speed
array[4]=x+4;    since compiler
array[5]=x+5;    doesn't have
array[6]=x+6;    loop unrolling */
array[7]=x+7;
}

    The program's maintainers will love you for it.

    Brillant!

    Hopefully, somebody who is looking at this code uses syntax highlighting, which would (again, hopefully) make the problem rather obvious.

  • (cs) in reply to Mike5
    Mike5:
    Dark Shikari:
    akatherder:
    I get my jollies by leaving intentionally misleading comments. It's almost as much fun as misnaming variables.

    Try something like this sometime then:

    if(do_loop){
array[0]=x;
array[1]=x+1;
array[2]=x+2; /* Unroll loop to
array[3]=x+3;    increase speed
array[4]=x+4;    since compiler
array[5]=x+5;    doesn't have
array[6]=x+6;    loop unrolling */
array[7]=x+7;
}

    The program's maintainers will love you for it.

    Especially since lines 3, 4, 5 and 6 are commented out.

    Mike5

    Umm...Syntax Highlighting is your friend? (Seriously, who doesn't use that these days?)

  • foo (unregistered) 
      void push(const value_type& _Val)
      {   // insert element at beginning
          c.push_back(_Val);
      }

  void pop()
      {   // erase element at end
          c.pop_front();
      }

    Now you have to ask yourself... is the bug in the code or the comment? WHICH is RIGHT? Ultimately it doesn't matter as long as the original author is consistently wrong.

    If they always call the back the beginning and the front the end then there's nothing computationally wrong with that. The system will work as expected all that has happened is you've obsfucated the code a little.

    But it IS a bit like having an itchy tag in your tee-shirt or a missing button hole. You aren't naked but you just can't get comfortable wearing that shirt.

  • Rolf (unregistered)

    Gonna love some comments. Sometimes wtf is worse in comments, like one about loop unrolling, with some of code commeted out? :P

    First part of article isn't a wtf to me, if I needed to know hex sometimes. I don't want to convert it each time I needed to know it.

    Second, in other hand... :P

  • gerrr (unregistered) in reply to foo
    foo:
      void push(const value_type& _Val)
      {   // insert element at beginning
          c.push_back(_Val);
      }

    void pop()
{   // erase element at end
c.pop_front();
}

    .... The system will work as expected all that has happened is you've obsfucated the code a little. ....

    Except when i call push('a') push('b') push('c') pop() //returns a instead of c pop() //returns b pop() //returns c instead of a

    I get a then b then c instead of c,b,a as implied by the function names. So no it does not behave as expected.

  • bobo (unregistered)

    Except in C++, pop doesn't return a value

  • JL (unregistered)

    As he put it, "Instead of using hex notation they added a very helpful comment!"

    It's likely that the coder didn't know VB.NET has hex notation. VB's hex notation doesn't show up in much code, and it doesn't resemble the notation used in most other programming languages.

    For the record: VB's hex notation is a prefix of an ampersand followed by an "H" -- e.g. "&HCAFEBABE". (Octal notation is similar: an ampersand followed by an "O" -- not a zero!) You can combine these notational prefixes with VB's literal type suffixes, too, to increase the range of silly words you can spell: "&HCABAL", "&HABACUS", "&HFECES", etc.

    I believe VB's hex notation is a throwback to the original Microsoft BASIC (via BASICA, QBasic, VB, etc.), so it may be one of the few examples of a current Microsoft product design decision that Bill Gates originally coded. I suppose at the time it was easy to parse, but I don't think it is as easy to read as C's hex notation.

  • Paul (unregistered)

    Some of you don't seem to know the difference between a stack and a queue. A queue is like a line at the DMV. You get in line, people at the front of the queue (i.e., the head of the queue) are taken care of, and eventually you get to the front of the line. First in, first out (FIFO). Typically, verbs like "put/get" or "add/remove" are used to describe these operations on queues.

    A stack is like a stack of paper. If you grab papers off of the top of the stack, and other people are putting stuff on the top of your stack, you may never get to the stuff on the bottom. Last in, first out (LIFO). The verbs used for stack operations are always push (place item on top of stack) and pop (remove item from top of stack). If you see push and pop, you expect the structure to be a stack. Conversely, if you have a stack, you expect the verbs to be push and pop. The verbs push/pop and the stack interface are used exclusively with each other. You can also use peek, but this is not specific to a stack, and just means show me the next value to be retrieved from the data structure without removing it.

  • Maarten (unregistered) in reply to clif
    clif:
    I had a manager who was also a great programmer. However when she told other developers to make changes to their code they would add her name in the comments and nothing else. It drove her nuts. Another favorite comment was the programmers initials and date. How useless is that.

    When someone F***** up, it's easy to find his code.

  • BigJim (unregistered)

    OK, no kidding, I saw this in an app that I inherited

    // Now let's do a Barbara Striesand and get back to the way we were... private void RestoreData(blah blah .....

  • (cs) in reply to Look at me! I'm on the internets!
    Look at me! I'm on the internets!:
    clif:
    I had a manager who was also a great programmer. However when she told other developers to make changes to their code they would add her name in the comments and nothing else. It drove her nuts. Another favorite comment was the programmers initials and date. How useless is that.

    At least we know who to blame.

    Even better. Now we know how to assign blame...

  • Dark (unregistered)

    I don't think hex notation would have improved the first code snippet much...

    Private Const ACK = &HA2 'Decimal 162 Private Const STX = &HA0 'Decimal 160 Private Const ETX = &HAF 'Decimal 175 Private Const CHANGE_TIMEDATE = &HBD 'Decimal 189 Private Const SETACTIVE = &HB1 ' Decimal 177 Private Const SELECT = &HB2 ' Decimal 178 Private Const RELEASE = &HB9 ' Decimal 185

  • Exick (unregistered) in reply to Jens
    Jens:
    clif:
    I had a manager who was also a great programmer. However when she told other developers to make changes to their code they would add her name in the comments and nothing else. It drove her nuts. Another favorite comment was the programmers initials and date. How useless is that.

    Ever heard of grep... I find it very usefull to be able to find all changes made by a certain programmer on a specific date.

    All well and good, it's fine to leave initials and a date in the comments when you make a change to the code. But the point was that the only comment added were the initials and date.

    P.S. Keeping track of who made what changes when is why source control tools were invented. :p

  • el jaybird (unregistered) in reply to JL
    JL:
    You can combine these notational prefixes with VB's literal type suffixes, too, to increase the range of silly words you can spell: "&HCABAL", "&HABACUS", "&HFECES", etc.

    I think my favourite silly hex word was one I actually found in production code in a military system. I forget what exactly, but it did have a useful purpose: 0xDEADBEEF.

    I'm guilty of (mildly) silly comments, but not here at work (yet). My school projects were known for comments saying things like

    ////////////////////////////////////////////////
//////// HERE THERE BE DRAGYNS !!! /////////////
////////////////////////////////////////////////

    And one which actually had a useful purpose and found its way into real code at my last job:

    //
//        TEST CODE BEGINS HERE!
//

               ////////////
               ////////////
               ////////////
               ////////////
               ////////////
               ////////////
               ////////////
               ////////////
               ////////////
               ////////////
      //////////////////////////////
       ////////////////////////////
        //////////////////////////
         ////////////////////////
          //////////////////////
           ////////////////////
            //////////////////
             ////////////////
              //////////////
               ////////////
                //////////
                 ////////
                  //////
                   ////
                    //
  • Sgt. Preston (unregistered) in reply to Look at me! I'm on the internets!
    Look at me! I'm on the internets!:
    clif:
    I had a manager who was also a great programmer. However when she told other developers to make changes to their code they would add her name in the comments and nothing else. It drove her nuts. Another favorite comment was the programmers initials and date. How useless is that.

    At least we know who to blame.

    Exactly! When I insert temporary debugging code, I add an initials-and-date comment. Once, when I stupidly let some of that 'temporary' code get released, the Support folks had no trouble determining exactly which twit in Development had screwed up. So I think it's a useful practice.

  • bpk (unregistered) in reply to Jens

    Ever heard of source control? It lets you "check in" and "check out" code and keeps a log of all the changes, who madethem, and on what dates.

  • bpk (unregistered) in reply to Jens

    Ever heard of source control? It lets you "check in" and "check out" code and keeps a log of all the changes, who madethem, and on what dates.

Leave a comment on “Comment in Earnest”

Log In or post as a guest

Replying to comment #:

Log Out

« Return to Article