Comments that piss me off



  • Not that I'm old, fat and balding (hey, if it's true, learn to deal with it) but the following:

    // throw exception
    throw new Exception("my helpful message");
    

    Sadly, I see a log more crap like the above than comments that are actually helpful (e.g., explain the intent when that's not clear from the code itself).



  • Many times I like to label blocks of code within a source file. Most times the labels succinctly describe the blocks. (With the labels I can quickly scan down through the file to find what I'm looking for.) But sometimes the labels may seem redundant...like "throw exception".



  • I agree, code comments should say why something does what it does, not what it is doing.

    Modern code practices should make the code self descriptive as to what it is doing, lie the above, yes we aer throwing an excpetion.

    Sadly a lot of programmers don't even know why and the rules where they work say "code should be commented" so we get this.

    Although in the past I have to admit I was guilty of this, but usually because I wrote all my commnets first as a kind of frame work I built in:

    // add the numbers

    //transform location

    //return value

    //raise exception if needed

    Then write the code between them and left the comments behind.  I'm a bit more experianced now and don't need this kind of help to stay on task.

     



  • I am just glad that in C# it has /// for doing summaries remarks, and adding other documentation related information.  The other thing I have come to love is the #region for denoting blocks of code for collapsing down sections thus improving readibility.



  • @KattMan said:

    I agree, code comments should say why something does what it does, not what it is doing.

    I don't know. There are certainly times when I'm doing something hacker-y with bits, or using a few functions with 7 integer arguments in conjunction with each other, which call for a little explanation as to what is going on. I don't trust the people who come after me to figure out my cleverness easily, so I leave "what's it doing?" explanations in my comments where I think it needs it.



  • @lettucemode said:

    @KattMan said:

    I agree, code comments should say why something does what it does, not what it is doing.

    I don't know. There are certainly times when I'm doing something hacker-y with bits, or using a few functions with 7 integer arguments in conjunction with each other, which call for a little explanation as to what is going on. I don't trust the people who come after me to figure out my cleverness easily, so I leave "what's it doing?" explanations in my comments where I think it needs it.

    Key point, "where I think it needs it"  at least you are thinking about it rather then just scattering them all over the place.  And I bet these comments are not usually along the lines of "add these bits together".



  • @KattMan said:

    Although in the past I have to admit I was guilty of this, but usually because I wrote all my commnets first as a kind of frame work I built in:

    // add the numbers

    //transform location

    //return value

    //raise exception if needed

    Then write the code between them and left the comments behind.  I'm a bit more experianced now and don't need this kind of help to stay on task.

     

    I still routinely do this, except I replace the comments as I go, and they're generally at a higher level:

     

    // render grids 1, 2, 3

    // render exchange rate stuff

    // render additional computations A1, A2, B, C, subtotal, D, total

     

    This could also be done using calls to initially-stub functions, but having dealt with lots of overdone lasagna code in the past, I prefer to write inline first and then refactor into functions to taste.

     

     



  • What's even worse are comments that are obsolete and wrong. I inherited some code once where the previous programmer would cut and paste a block of code, including comments, and change what it does without changing the comments. Those comments are of negative value.



  • @KattMan said:

    I agree, code comments should say why something does what it does, not what it is doing.

    For even better comments you should also be saying why you can't/shouldn't do it another way if there are multiple solutions.



  • I worked at a shop where home-grown source control automatically rejected any code with a comment-line-to-functional-line ratio of less than 0.3-ish. As you can imagine it led to an awful lot of code just like the OP's in order to pass validation...



  • @rstinejr said:

    Sadly, I see a log more crap

    Base 10 or natural logs?



  • @Cassidy said:

    @rstinejr said:

    Sadly, I see a log more crap

    Base 10 or natural logs?

    If the log rolls over we'll all be dead!

     



  • @Cassidy said:

    @rstinejr said:

    Sadly, I see a log more crap

    Base 10 or natural logs?

    Spell-checker saves me from some goofs, but not nearly all of them. :-(



  • //Player Jumped
    function bool DoJump( bool bUpdating )
    {
    	if (bJumpCapable && !bIsCrouched && !bWantsToCrouch && (Physics == PHYS_Walking || Physics == PHYS_Ladder || Physics == PHYS_Spider))
    	{
    	if ( Physics == PHYS_Spider )
    			Velocity = JumpZ * Floor;
    		else if ( Physics == PHYS_Ladder )
    			Velocity.Z = 0;
    		else if ( bIsWalking )
    			Velocity.Z = Default.JumpZ;
    		else
    			Velocity.Z = JumpZ;
    		if (Base != None && !Base.bWorldGeometry && Base.Velocity.Z > 0.f)
    		{
    			Velocity.Z += Base.Velocity.Z;
    		}
    		SetPhysics(PHYS_Falling);
    		return true;
    	}
    	return false;
    }

    From the Pawn class, from which players, AI, cars, planes, boats, etc. extend from...

    What is bUpdating?
    Who knows?
    Who thought it necessary to comment this with "Player jumped?"
    What does the return value signify? I'm guessing if we actually jumped or not?

    Poor commenting pisses me off immensely.

    Also, I have absolutely no idea how to indent that code here. If you want it indented, here's a pastebin.

    [Fixed formatting. -ShadowMod]



  • @nexekho said:

    Also, I have absolutely no idea how to indent that code here. If you want it indented, here's a pastebin.

    You can just use <pre> tags in the HTML editor.



  • Ah, damnit, that's the one, I could've sworn I tried that. Thanks.

    Can't edit my post so I can't fix it.



  • Geez... that IS bad code.  Who uses tabs?



  • @Sutherlands said:

    Geez... that IS bad code.  Who uses tabs?

    I prefer tabs because it's simple for each person to customize their editor to display it in their preferred mode. For example, the Linux kernel uses 8-space tabs, which looks fucking ridiculous to me. I prefer 2-space tabs (I just need to see that stuff is indented--it doesn't have to fly off the screen.) However, alignment should still be done with spaces (because variable-length tabs won't align properly).



  • @Anketam said:

    ...The other thing I have come to love is the #region for denoting blocks of code for collapsing down sections thus improving readibility.

    Please stay away from my code. I hate #regions, code folding works just fine. If you need to separate a large section of code, use a partial class.



  • @Jaime said:

    @Anketam said:

    ...The other thing I have come to love is the #region for denoting blocks of code for collapsing down sections thus improving readibility.

    Please stay away from my code. I hate #regions, code folding works just fine. If you need to separate a large section of code, use a partial class.
    Same.



  • I inherited 100,000 lines of code with a ton of comments. 95% of the comments are of the form "4/1/2005 CEJ Bug #419". I don't think there's a single useful comment in the entire application suite.



  • @Sutherlands said:

    Geez... that IS bad code.  Who uses tabs?

    Pretty much all browsers have them these days.



  • @KattMan said:

    I agree, code comments should say why something does what it does, not what it is doing.

    Modern code practices should make the code self descriptive as to what it is doing, lie the above, yes we aer throwing an excpetion.

    Sadly a lot of programmers don't even know why and the rules where they work say "code should be commented" so we get this.

    Do software houses have policies (or guidelines) on code comments?  Or is it assumed that all experienced coders now this stuff and the less-experienced just pick up tips along the way?

    I only ask this because I have a viewpoint on commenting that derives from my limited programming experience. In general I advocate:

    1. comments tell you why, the code tells you how - code is simply a technique to solve a problem. Comments tell us why that particular technique was chosen, what else was considered, what situations would cause us to reach this this section of code, etc.
    2. code is for machines, comments are for humans - variable/object/class names can be meaningful or meaningless, it matters not to the machine because they just use it as a pointer reference. We can make them long, wordy and self-describing, but there's only a certain amount of work we can do in transforming machine-readable stuff into human-readable stuff. Rather than expend the effort of making it all self-describing, leave it be and use comments to explain yourself. Comments are ignored by the machine, feel free to expand as much as you want. Code is parsed by the machine; changing it may have unwanted effects.
    3. comments should be at a higher level (summarise) or lower level (demystify) than the code to improve understanding - avoid technical or programming terms in comments, choose synonyms where possible.
    4. comments should look like comments, and not lines of code that are commented out - use additional characters to make comments stand out as annotation, distinguishing them more strongly from code, helping the reader to draw their attention.
    Right or wrong, people? Anybody got any commenting standards they can throw into the ring?


  • I would say comments should also tell you when if it's executed only under circumstances. (i.e. this event fires when the game over signal fires, this event fires when the game closes would have saved me some confusion)
    Also, when NOT to use this function.

    Lastly, what this function affects. I recently had a bit of a cock-up involving an inventory manager because I assumed that calling a texture swap function on a Scaleform object only affected that Scaleform object - no comment to the contrary - when in fact it swaps that resource in every Scaleform object running.


  • Trolleybus Mechanic

     

    Comments that piss me off

    First!



  • @Jaime said:

    Please stay away from my code. I hate #regions, code folding works just fine. If you need to separate a large section of code, use a partial class.
     

    Got anything for VS that lets you fold any block, not just classes and methods? That would be handy. #region is shitty.



  • yup



  • @Jaime said:

    I inherited 100,000 lines of code with a ton of comments.

    Yeah, but after taxes that's only 40,000 lines of code.



  • @Cassidy said:


    I've always taught "who, when, why".

    Who wrote this code? Who do I go to when I have questions? Who do I blame for the steaming pile of bantha pudu?

    Why was it written? What business need required someone to put time into writing this? Why did they pick this algorithm over others? What other approaches did they consider and reject, and why?

    The comment should only answer "how" if the code is gnarly and twisted. I also think that's a good clue to the programmer that they should look for another way of doing the job. Of course, some gnarly and twisted code cannot be avoided.

    Cassidy, that statement about comments summarising or demystifying is great. I'm going to use it in class.

    I also agree with the "comments should look like comments" statement. Comments are in the plain language of whatever you speak. That means complete sentences with punctuation and capitalisation.



  • @havokk said:

    Who wrote this code? Who do I go to when I have questions? Who do I blame for the steaming pile of bantha pudu?

    Why was it written? What business need required someone to put time into writing this?

    Source control check in comments should answer theses questions.



  • @Cassidy said:

  • code is for machines, comments are for humans - variable/object/class names can be meaningful or meaningless, it matters not to the machine because they just use it as a pointer reference. We can make them long, wordy and self-describing, but there's only a certain amount of work we can do in transforming machine-readable stuff into human-readable stuff. Rather than expend the effort of making it all self-describing, leave it be and use comments to explain yourself. Comments are ignored by the machine, feel free to expand as much as you want. Code is parsed by the machine; changing it may have unwanted effects.
  • Variables and class names should describe what they do/are.  Self-describing is also self-documenting, and you don't have to worry about the comments not being kept up to date.  Comments should be used to explain tricky parts, not that you're picking all ints > 12 out of a list.


  • @Sutherlands said:

    @Cassidy said:

  • code is for machines, comments are for humans - variable/object/class names can be meaningful or meaningless, it matters not to the machine because they just use it as a pointer reference. We can make them long, wordy and self-describing, but there's only a certain amount of work we can do in transforming machine-readable stuff into human-readable stuff. Rather than expend the effort of making it all self-describing, leave it be and use comments to explain yourself. Comments are ignored by the machine, feel free to expand as much as you want. Code is parsed by the machine; changing it may have unwanted effects.
  • Variables and class names should describe what they do/are.  Self-describing is also self-documenting, and you don't have to worry about the comments not being kept up to date.  Comments should be used to explain tricky parts, not that you're picking all ints > 12 out of a list.

    Like most things in software engineering, it requires good judgment. I write descriptive code but if there's a need I'll add comments rather than have 30 character variables or methods.



  • @morbiuswilters said:

    Like most things in software engineering, it requires good judgment.

    Of course.


  • @Sutherlands said:

    @Cassidy said:

  • code is for machines, comments are for humans - variable/object/class names can be meaningful or meaningless, it matters not to the machine because they just use it as a pointer reference. We can make them long, wordy and self-describing, but there's only a certain amount of work we can do in transforming machine-readable stuff into human-readable stuff. Rather than expend the effort of making it all self-describing, leave it be and use comments to explain yourself. Comments are ignored by the machine, feel free to expand as much as you want. Code is parsed by the machine; changing it may have unwanted effects.
  • Variables and class names should describe what they do/are.  Self-describing is also self-documenting, and you don't have to worry about the comments not being kept up to date.  Comments should be used to explain tricky parts, not that you're picking all ints > 12 out of a list.

    True, that!

    Kent Beck came up with the notion of "code smells" -- characteristics that are not errors per se but do indicate a potential problem. The analogy he used is detecting a dirty diaper by a poopy smell -- the diaper may not need changing, but it should be checked. Heavily commented code made the list of code smells. But cutting back comments to the minimum is only possible if variables and methods have meaningful names.

    And on that note, a very senior programmer in my shop, now the hands-on manager of my team, ALWAYS names the the variable containing a function's return value "result".


Log in to reply