5 ms·

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

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.

trixie_ 6y ago
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.
- RandallBrown 6y ago
  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.
  - jbay808 6y ago
    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.
    - tigershark 6y ago
      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.
      - jbay808 6y ago
        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.
        tigershark 6y ago
        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

trixie_ 6y ago

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.

RandallBrown 6y ago
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.
- jbay808 6y ago
  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.
  - tigershark 6y ago
    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.
    - jbay808 6y ago
      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.
      - tigershark 6y ago
        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