This was a thing at my last job. The lack of comments always made me cringe. While not every line needs a comment, there's a reason why comments would be useful, especially in security software.

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.

The self documenting one always gets me. It's not like the person has never read code that is difficult to understand.

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.

Ya, but with a security product there are important considerations and while we commented on areas where we fixed a bug due to something fixable, it was a pain in general.

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

It seems to be fairly common for experienced programmers to point to unit test code as a way to explore or understand an open source software project. I don't doubt that this works for them, but it definitely doesn't work for me. When I'm trying to explore a new software project, the first thing I want to do is find the relevant "entry point," which is arguably the exact opposite end from the unit test code.

Tests that target the surfaces of the project (public APIs, endpoints, etc) and code examples start to blend together at some point. "Here's a basic example that should do X" sounds a lot like "Do something basic and assert it does X".

One thing that I like about Rust is that they actually allow you to merge those two into one. In your documentation of anything, you can include code snippets, and those code snippets become tests that can ensure that the documented behavior still applies to the current code.

Yes, this is how I use them as well. I’ll go to the unit tests after I have a decent understanding of the project and am looking for examples that aren’t covered in the README.

I think the biggest problem with using unit tests for this purpose is that unit tests tend to (rightfully) spend a disproportionate amount of lines of code on edge cases.

Where applicable, this is what doctests are for, and they're magical. ... where applicable.

Clear code and clear tests absolutely don’t need comments that explain them if they are really clear, at least for me. Comments are extremely useful to explain something unexpected. Commit messages are too limited to explain properly a use case, but linking to a Jira with the proper explanation does the trick. From the tests you can see both the typical use cases and the correct way of using some piece of code and have a guarantee that the code respects the specification. With the comments you have none of this guarantees. I had the opposite experience from you apparently, the people that I worked with that used excessive comments were not up to par with the rest of the team. Also it may related to the mental model, comments just break my flow and make more difficult for me to read the code.

Right you are exactly the kind of person I'm talking about. You think your code is clear. It is not. The logic your code performs is the distilled by-product of higher level reasoning. Reasoning that should be the basis of your comments.

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.

If someone's code isn't self explanatory from the naming and organization, why would you expect their comments to do a better job?

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 don't even mind if the comments restate what the code says. The code only says what it does, not what it is intended to do.

The tests say what the code is supposed to do. And, unlike the comments, they cannot be out of sync with the code because they will fail.

Ok, so for example, let's say I have a function npow2(x) that returns the next power of two above x, unless x is a power of 2 already, in which case it returns x. And I want to use this to get the next power of 2 below x.

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.

Adding a comment there is not useful, it should be added only in the function definition if needed. In this case it’s needed because the function does something unexpected. I would call it nextPower2(n) rather than npow2 and add a comment in the definition saying that the function returns n if n is a power of 2 because it’s unexpected and it can’t be inferred looking at the function name. As I said before, comments for unexpected behaviours are not only perfectly fine but extremely important. Also removing all the useless comments will increase the relative importance of the ones remaining since you will have only comments for really important stuff.

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

The comments are informing the reader about the trick that turns npow2 into prevpow2. Your reply seems focused on npow2 itself, not the line npow2(x+1)/2 that I said deserves a comment. I agree that npow2 should have the tests and documentation that you say, but in my example I'm taking that function as given, eg. by a library.

It's a matter of judgement. I've read code in languages I don't know, even, where I could immediately figure out what was going on without reading any comments. I've also patched libraries in ten minutes without reading comments. It's certainly possible to write code that doesn't need comments, though perhaps, we're not the best people to judge when that's the case or not for our own code.

Same here. Though if you are putting thought into the code you are writing - the logic, the structure, etc.. Then those thoughts should probably be written down as well as comments.

Self-documenting code is not a judgment that you can pass on your own code: that's the role of code review.

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.