One place I worked required a comment for every line of code

/* assign 1 to a */

a = 1;

This is worse than no comments

With good variable naming and clearly-named functions little commenting is necessary ... who'm I kidding .. we still see shit like this

int NumObjs;

Is this a count? An index? An offset? Why are letters omitted? What type is the object? Nobody should ever use a name like "number" and everything should be fully spelled out except maybe supremely obvious abbreviations like Info for Information.

But omitting letters is ... cute.

In onee group I worked in at Microsoft we had API that were always fully spelled out; DM_MeteringInitialize(...). Then one guy implemented a secure clock (so people couldn't defeat a timeout by changing the system clock) and wrote

DM_SecClk...

WHY.

Comments should be at the block level, explaining what a block is doing; having a comment black atop every slf-documenting function is just compulsive.

American Software Developer living in Vietnam. Classical musician (guitar, woodwinds), weightlifter, multilingual, misanthrope • XY

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store