15 ms·

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..

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.

baddox 6y ago
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.
- henryfjordan 6y ago
  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".
  - baddox 6y ago
    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.
    - dllthomas 6y ago
      Where applicable, this is what doctests are for, and they're magical. ... where applicable.
  - dfinninger 6y ago
    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.
  - DreadY2K 6y ago
    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.
dnautics 6y ago
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.
- trixie_ 6y ago
  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.
selykg 6y ago
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.
- trixie_ 6y ago
  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.
  - selykg 6y ago
    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
deleted 6y ago
[deleted]
tigershark 6y ago
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.
Kwantuum 6y ago
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.

baddox 6y ago

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.

henryfjordan 6y ago
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".
- baddox 6y ago
  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.
  - dllthomas 6y ago
    Where applicable, this is what doctests are for, and they're magical. ... where applicable.
- dfinninger 6y ago
  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.
- DreadY2K 6y ago
  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.

dnautics 6y ago

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.

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

selykg 6y ago

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.

trixie_ 6y ago
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.
- selykg 6y ago
  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

deleted 6y ago

[deleted]

tigershark 6y ago

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.

Kwantuum 6y ago

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.