TIL: comment smells

Do you know that feeling of revelation when someone labels a concept you haven't quite put your finger on yet?

I recently experienced it when Matt Godbolt introduced me to the idea of 'comment smells'. This was in his talk titled 'Correct by Construction: APIs That Are Easy to Use and Hard to Misuse', which is worth a listen in its entirety.

Matt brings up comments in code that instruct callers of an API to invoke additional setup or teardown tasks for said API to work. Rather than burdening callers with reading & acting on instructions held in comments, he urges programmers to surface these constraints in the API itself, i.e. via code, contracts and function signatures.
Turn messages for humans into messages for the compiler (preferably ones that raise compile-time errors!).

Matt identifies 'apologetic comments' as an anti-pattern, and as prime candidates for elimination and encoding into the API itself.

The whole talk is worth watching, even for someone who's never written a line of C++ in their life.
The talk is available on YouTube, and it is at 31:10 that 'comment smells' are tackled.

Image: Fig. 113 from Plain Home Talk (1896) by Edward B. Foote, out of copyright.