If I had a nickel for every programmer who thought their code was so good it didn't require comments... or thinks somehow that unit tests make up for comments... only to come back years later and have no idea why the logic is working how it is.
I learned a lot of bad habits there and I'm glad I no longer work there.
Their excuses were literally "no one reads comments" "no one keeps comments up to date" "my code is self documenting" etc.
Yet they think it is just other people who write 'bad' code. Their own code can't possibly be bad. In fact it is so good that it 'documents itself'. It's just a statement that drips with arrogance.
Decisions maybe don’t belong in code but with a security product I feel there has to be some quality level of comments to explain why and how. Someone coming along later can’t be expected to be in the authors head and the author won’t remember all this stuff years later when it might matter or need to be rewritten.
Such a shit show
People reading your code will not be in the same mind state that you were in when you wrote it. That is what the comments are meant to assist with.
If you write comments for anyone, write comments for yourself first. You will not remember years from now the reasoning that went into the code your wrote.
The vast majority of comments I see are completely useless, either giving incorrect/outdated information or restating exactly what the code says. I've even made comments nearly the same color as the background in my text editor so it's easier for my brain to skip them.
Comments certainly can be useful, but I think they should be used extremely sparingly.
I can write:
y = npow2(x+1)/2; //get y such that the next power of 2 above y is at least x.
The comment says exactly what the code does, but at least it also says that that's what it's intended to do. This lets a reviewer check correctness, add optimizations, and also understand the intentions at a glance. The why is important too, of course.
Now I could alternatively add unit tests that specify a large number of input cases in which the output happens to be the previous power of 2. But unless I make the test cases exhaustive, I'm only hinting at what this code should do, not defining or explaining it.
I could break this out into a function too, called prevpow2(x), which might or might not be appropriate in this case. But if so, I'd expect that function to have a docstring explaining... exactly the same thing as the above inline comment: what the function supposedly does.
Edit: And anyway in the tests you should have at least these two test cases:
Test nextPower2 returns n if it’s a power of 2
Test nextPower2 returns the next power of 2 if n is not a power of 2
95% of the code you write day to day should be clear enough that someone who didn't write it can understand it on first read (the reviewer). If they can't, you probably need to rewrite the code so that it is clearer, not comment it. That's what self-documenting code is.
Instances where the code needs comments to be understandable are rare.