Birb: How the fuck is water doing that °v°

Senior engineer: the glass is self documenting.

/**
 * @brief This is the coffee cup class
 * 
 * This class describes a cup or mug that neatly integrates a
 * container for vectors of cCoffee instances with a fully
 * functional handle to carry the cup or mug around. Used for 
 * pretty much everything.
 */
class cTallGlass : public cGlass {

// This might be a glass
Glass* glass = dynamic_cast<Glass*>(container);

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

50% water, 50% gas mixture.

It's not a glass, it's the

hydrationContainerManagerObjectFactory

Not to be confused with the

hydrationContainerManagerTypeFactory

Which is the template

//don't remove this comment or else

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

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

While filling the glass: glass is half full

While emptying the glass: glass is half empty

Context matters

Comment would be whether glass is being emptied or filled

Opportunist... "It's an empty glass. I drank it while you were arguing."

Engineer: The glass is too big!

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. 😊🥛

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

// TODO: Class description here to satisfy linter

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

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.

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.

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

You guys are getting code comments???

Marketing: the glass is perfectly dimensioned to transport that amount of water without spilling anything! Buy yours now for a discount! Terms and conditions may apply.