4 ms·

You would not be allowed to do any of this if you worked on my team. Do not put documentation in code, put it in documentation. Comments break up code, consta

You would not be allowed to do any of this if you worked on my team. Do not put documentation in code, put it in documentation. Comments break up code, constantly flipping between reading the language and reading English. Comments are failures on the part of the programmer to describe the implementation clearly in the language being used. The lesson you should have learned is to recognize that it's okay to fail in this way, but to still consider it a failure.

DSMan195276 8y ago
I work on a team with the same policy, but personally I think it's a bit silly. There's nothing that guarentees that a version of the code that explains everything only in code is actually easier to undertsand, but that's the assumption being made. In a lot of cases I think it tends to be the opposite - adding more code just for the sake of 'explanation' bloats the code to much larger lengths and ends up making it harder to understand than if you just added a few lines of comments that explained the exact same thing. In that situation, adding comments is not a 'failure', it's just another option for making your code easy to understand.
christophilus 8y ago
You wouldn’t be able to contribute to the Redis or SQLite codebases, then, as they are heavily and helpfully commented and are almost always near the top of the list of answers when people ask the question: “What are some examples of exemplary codebases?” In fact, it was reading those projects and then returning to my workplace’s uncommented source that convinced me to change my philosophy on commenting.
- kungtotte 8y ago
  I just looked up a sample of the SQLite codebase[0] and it seems to align with what most people are saying here, to keep a minimal amount of comments and the ones that are there should comment what the code can't tell you. [0] https://sqlite.org/src/fdiff?v1=7c288b4ce309b5a8&v2=8efa2c813b3f6a83 https://sqlite.org/src/fdiff?v1=7c288b4ce309b5a8&v2=8efa2c81...
- diminoten 8y ago
  The SQLite project is a good example of a codebase despite this decision, not because of it. SQLite is nearly 20 years old, and their position on this topic is reflected in their policy. And Redis makes no such requirement. You are wrong.

DSMan195276 8y ago

I work on a team with the same policy, but personally I think it's a bit silly. There's nothing that guarentees that a version of the code that explains everything only in code is actually easier to undertsand, but that's the assumption being made. In a lot of cases I think it tends to be the opposite - adding more code just for the sake of 'explanation' bloats the code to much larger lengths and ends up making it harder to understand than if you just added a few lines of comments that explained the exact same thing. In that situation, adding comments is not a 'failure', it's just another option for making your code easy to understand.

christophilus 8y ago

You wouldn’t be able to contribute to the Redis or SQLite codebases, then, as they are heavily and helpfully commented and are almost always near the top of the list of answers when people ask the question: “What are some examples of exemplary codebases?” In fact, it was reading those projects and then returning to my workplace’s uncommented source that convinced me to change my philosophy on commenting.

kungtotte 8y ago
I just looked up a sample of the SQLite codebase[0] and it seems to align with what most people are saying here, to keep a minimal amount of comments and the ones that are there should comment what the code can't tell you. [0] https://sqlite.org/src/fdiff?v1=7c288b4ce309b5a8&v2=8efa2c813b3f6a83 https://sqlite.org/src/fdiff?v1=7c288b4ce309b5a8&v2=8efa2c81...
diminoten 8y ago
The SQLite project is a good example of a codebase despite this decision, not because of it. SQLite is nearly 20 years old, and their position on this topic is reflected in their policy. And Redis makes no such requirement. You are wrong.