CodeSOD: Valuable Comments

When we share code comments, it's usually because they demonstrate some lack of awareness or some carelessness about what's going on. A comment warning "I know I shouldn't do this" or a comment that contradicts the code in a funny way, that's usually what we share.

But today's submission, from Dewey, is a bit different. Dewey wrote the comment, and it was in preparation for some serious refactoring. So this comment is the product of someone spending time to accurately analyze and understand a method, documenting its behavior, and explaining it so the code could be changed to something better. The WTF here isn't the comment, but the code it describes.

/** Get the field value, stripped of accelerator key information while side-effecting some global variables that affect the way @link #setAcceleratorMnemonic(JMenuItem)} behaves in subsequent calls....*/

"while side-effecting some global variables" is exactly the kind of thing you want to see in a code comment. Well, maybe not, but it's the kind of thing I like to see when trawling through submissions.

It took Dewey thirty minutes and a careful trace through three different methods to be able to understand the code well enough to write this.

[Advertisement] Keep the plebs out of prod. Restrict NuGet feed privileges with ProGet. Learn more.