Comments vs. Meaning



  • I found this block in our production code:

        //for counting the matching attribs for measuring how much one matches
        int counter
    
        /** flag to print some detailed infos */
        boolean verbose
    
        //the config.xml file
        File file
    
        //should be a log4j-Logger
        Logger logger
    

    In addition: this is one of two groovy classes in a program consisting of 500 java classes.
    Questions:

    • What is the meaning of "how much one matches"?
    • Why use two different ways to denote comments?
    • Why do we need comments where cute names would do?
    • If it *should* be log4j-logger ... Is it? What if it isn't? Or maybe we are not sure what it is? What about looking at, or adapting, the import statement above?


  •  @maja said:

    What is the meaning of "how much one matches"?

    I presume it's comparing two objects and returning the number of "attribs" that are the same in both of them. What these two objects are might or might not be apparent from the context, I don't know because you didn't post the context. Okay, it could be better, but whoever wrote this is at least making an effort. None of this /*add 1 to i*/ nonsense.

    @maja said:

    Why use two different ways to denote comments?

    Because they were written by two different people or added at two different times or one of them was copy-pasted from elsewhere in the program. That's usually how it works.

    @maja said:

    Why do we need comments where cute names would do?



  • The two comment styles have a functional difference: Only the second comment would appear in a Javadoc.

    Of course, if they all have the same access, why would one do that?



  • Jesus, I hate comments like that. It makes me want to punch someone.



  • @morbiuswilters said:

    Jesus, I hate comments like that. It makes me want to punch someone.

    You need something with more authority than a mere fist. I, as usual, recommend pulling the GAU-8 out of your back pocket and using that in some way.



  • @Snowyowl said:

     @maja said:

    What is the meaning of "how much one matches"?

    I presume it's comparing two objects and returning the number of "attribs" that are the same in both of them. What these two objects are might or might not be apparent from the context, I don't know because you didn't post the context. Okay, it could be better, but whoever wrote this is at least making an effort. None of this /add 1 to i/ nonsense.

    That is a point that it could be worse.

     //the counter
        int counter
    
        /** the verbose */
        boolean verbose
    
        //the file
        File file
    
        //the logger
        Logger logger


  •  I think my favorite comment ever seen in production code:

     count++; // Increment count



  • @MiffTheFox said:

    @Snowyowl said:

     @maja said:

    What is the meaning of "how much one matches"?

    I presume it's comparing two objects and returning the number of "attribs" that are the same in both of them. What these two objects are might or might not be apparent from the context, I don't know because you didn't post the context. Okay, it could be better, but whoever wrote this is at least making an effort. None of this /add 1 to i/ nonsense.

    That is a point that it could be worse.

     //the counter
        int counter
    
        /** the verbose */
        boolean verbose
    
        //the file
        File file
    
        //the logger
        Logger logger

    Reminds me of the time when we had Stylecop enforcing xml comments, so somebody decided Ghostdoc was a good idea.

    Needless to say we quickly binned one... then finally the other.

    I'm still occasionally coming across and removing useless undocumentation from some of the older bits of our framework code that isn't touched often.



  • Guys, thank you for your empathy - it does give me some closure posting this here and consolation reading your comments.

    To provide a few answers, I dug into our vcs one more time:

    @Snowyowl said:

    Because they were written by two different people or added at two different times or one of them was copy-pasted from elsewhere in the program. That's usually how it works.

    Yeah ... must be one of those, although: one programmer. One class that's used only in one place. Two groovy classes amidst hundreds of java classes, none of these lines appear anywhere else.
    The lines with the different comments were added within 28 days of each other. The class was created one year before and finally sent to the happy coding grounds, after 4 more years, today (by someone else). The class was changed many times before and after these lines were added, two of those lines were even changed two years after they had been added.

    @Medinoc said:

    The two comment styles have a functional difference: Only the second comment would appear in a Javadoc.
    Of course, if they all have the same access, why would one do that?

    You got a point there. This is all internal code, not even an interface to another person in the same company. Plus this class is used only in one place.

    Oh, and "verbose" is actually set once, but in a context where the only place where it might matter is not called. Yeah I know, vestigia.

    Since this is only the simplest incarnation of evil that I was able to extract, I feel like looking at a car crash: I know it's tactless staring at the misery, but keep being drawn into it. Then I wake up two hours and 5 reverts later and notice that I must go home now to stay sane.

    @morbiuswilters said:

    Jesus, I hate comments like that. It makes me want to punch someone.

    Thanks for your sympathy. I really needed that.

    I have a token of gratidude for you:

    assertEquals(over.entrySet().size(), 8 + 1); // LATER: override->9+1
    


  • Here's my favorite comment ever. This is in an initialization list in a constructor:

    m_zoomtracker(-1.1311228f) // This number is not as magic as it looks!

    Oh, thank you so much for that comment! That explains exactly why this particular value, out of four billion possible floats, was there. Please, don't use defines or const variables. Just let me know the number is not as magical. I don't know what's worse, that the person used a magic number, that they know magic numbers are bad, or that he wrote a comment to let other people know the number was there for a reason (as opposed to other numbers he may have put in the code? :shudder:).

    The best part: This value appears in the constructor of seven classes. With the exact same comment.


  • Discourse touched me in a no-no place

    @Kian said:

    m_zoomtracker(-1.1311228f) // This number is not as magic as it looks!

    Oh, thank you so much for that comment! That explains exactly why this particular value, out of four billion possible floats, was there. Please, don't use defines or const variables. Just let me know the number is not as magical. I don't know what's worse, that the person used a magic number, that they know magic numbers are bad, or that he wrote a comment to let other people know the number was there for a reason (as opposed to other numbers he may have put in the code? :shudder:).

    The best part: This value appears in the constructor of seven classes. With the exact same comment.

    Out of interest, is another of the values 0.3808219f?



  • @Kian said:

    Here's my favorite comment ever. This is in an initialization list in a constructor:

    m_zoomtracker(-1.1311228f) // This number is not as magic as it looks!

    Oh, thank you so much for that comment! That explains exactly why this particular value, out of four billion possible floats, was there. Please, don't use defines or const variables. Just let me know the number is not as magical. I don't know what's worse, that the person used a magic number, that they know magic numbers are bad, or that he wrote a comment to let other people know the number was there for a reason (as opposed to other numbers he may have put in the code? :shudder:).

    The best part: This value appears in the constructor of seven classes. With the exact same comment.

    Maybe the commenter has misunderstood what magic numbers means, and just assumes that because he derived it using mundane earthly methods, it lacks the magical potency of others numbers calculated by voodoo.


  • Discourse touched me in a no-no place

    @Snowyowl said:

     @maja said:

    What is the meaning of "how much one matches"?

    I presume it's comparing two objects and returning the number of "attribs" that are the same in both of them. What these two objects are might or might not be apparent from the context, I don't know because you didn't post the context. Okay, it could be better, but whoever wrote this is at least making an effort. None of this /add 1 to i/ nonsense.

    @maja said:

    Why use two different ways to denote comments?

    Because they were written by two different people or added at two different times or one of them was copy-pasted from elsewhere in the program. That's usually how it works.

    @maja said:

    Why do we need comments where cute names would do?


Log in to reply