You guys are getting code comments???

That’s not a good comment. What it is should be clear from the naming and context. A good comment explains the why when that is not obvious:

// This glass is at 50% capacity because we don't want it to overflow if it rains

Opportunist… “It’s an empty glass. I drank it while you were arguing.”

It’s not a glass, it’s the

hydrationContainerManagerObjectFactory

Not to be confused with the

hydrationContainerManagerTypeFactory

Which is the template

//This a glass // To get the quantity and type of content use
// glass->qty : float
// glass->content : glass_content

// This is a Glass class
class Glass {
     filled(halfFull,  halfEmpty) {
         this.halfFull;
         this.halfEmpty;
         }
}

The current legacy code I’m dealing with is full of these:

// TODO: Class description here to satisfy linter

AI loves inserting comments like this.

Either that or 20-line comments documenting the bugs in the old code, what this code does differently, and the exact implementation.

Comments describing the exact implementation become stale very quickly. Comments shouldn’t explain what the code does (eg “add two to rowCount”); they should explain why it does it (eg “include header and footer row in count too”). Extra details are what the commit message is for, and history is what source control is for.

I call it out in a lot of my code reviews (“code looks good but clean up the AI slop comments before landing”) but a lot of other developers don’t care as much about code and documentation quality.

Unless it is in a vacuum, the glass is full.

50% water, 50% gas mixture.

Normal person: Nobody asked you if it was a glass.

Engineer: this glass is twice as big as it needs to be.

Glass _glass = new Glass(); //make variable glass of type glass and make a new glass
///<captainusefuldoc>Gets the glass</captainusefuldoc>
Glass getGlass() => _glass; //get the glass in _glass

Commented out glass is certainly a problem (if it’s not only a comment) as the instance of object is created elsewhere but there’s some more problems in the code:

-Software tester removes the glass but the water still stands there in the shape of the glass.

-QA tries to pour the water in to the glass but water doesn’t register and the glass doesn’t fill.

-Performance testing notes that rendering the glass needs some optimization since the glass doesn’t fill over 50% before being out of memory.

-Junior programmer can’t get the glass to run since the liquids library wasn’t locked down and got an incompatible update.

-Automation testing results in to a crash with a screenshot and logs that point out that glass frontend use the old version of the glass backend API leading the glass to freeze.

-External testing points out that there’s a bug in the glass but they can’t identify it.

//don’t remove this comment or else

IT support chatbot when the client asks how to get an empty/full glass to display: You’re absolutely right! I couldn’t have said it better myself: This is a glass. 😊🥛