4 ms·

I am still in the middle of reading the book and have not read the part about comments, but so far I have yet so see good comments in source code up to a point

I am still in the middle of reading the book and have not read the part about comments, but so far I have yet so see good comments in source code up to a point where I have a rather biased opinion on comments: * good software needs hardly any comments: small methods with good naming facilitate readability * unit tests are superb documentary as every dev can see how it is used and how it works at runtime. * meaningful documentation is hardly ever provided in source code: purpose of abstraction layers and modules, how one class/module relates to another and so on (design and architecture).

_wp_ 5y ago
I strongly agree with your first two points. Good naming supplants the need for commenting. I find diagrams a far terser communication tool of architecture than comments.
- matthiaswh 5y ago
  The book has an entire chapter called "Choosing Names" and another titled "Comments Should Describe Things That Aren't Obvious from the Code". Yes, good naming supplants the need for many comments, but the author goes into much greater detail about when and why comments are helpful even when you have given deep consideration into naming things.
  - smichel17 5y ago
    I wish we had better tooling for showing the git blame inline like comments. I'd rather put a one line comment "read the commit log for this line" which some editor could inline or pull up quickly than litter the source with prose (but either is better than nothing).
    - TeMPOraL 5y ago
      Except the same belief in "self-documenting code" that makes people ignore the need for comments, also makes them ignore the need for writing proper commit messages. Git blame won't save you, if every commit message is just a one-liner like "fix foo in bar". Viewed from the other end: commit messages are essentially comments over changesets. If you write those well, you can use the same approach to write good comments for your types, functions and modules. See also https://news.ycombinator.com/item?id=27009308 https://news.ycombinator.com/item?id=27009308 on what I consider to be good style of commit messages (scale up or down, depending on the size of your commits).
    - nonameiguess 5y ago
      Some code is intended to last, potentially a very long time, and has to be separable from history metadata. If for no other reason, git trees can get really big. I had a large monorepo at an old job with some code dating back to the mid 80s and it took 10 minutes to clone because of all the history. When we finally gave up on Kiln, years after its own developers abandoned it, we migrated only the code and not the history. After that, you could clone the entire repo in 10 seconds instead of 10 minutes. They key is you want to be able to do something like that without losing crucial information. So anything that absolutely has to be there to understand what code is doing should be directly embedded in the code, that is, it needs to be a comment, not a commit message.
pdamoc 5y ago
Even good software runs in a context. The last commit I did was just to add a comment about a specific ordering in an argument to a function call that had to be that way to compensate for a bug in the library from where the function was imported.
Cthulhu_ 5y ago
Counterpoint: API documentation. I'd rather read a high level overview of a component + its methods than have to open up and read (= decode) the contents, or trudge through the unit tests. If I'm working with it on a lower level then maybe.
- quanticle 5y ago
  Counter-counterpoint: that documentation should not exist as comments in the code, but as separate, properly formatted documentation. Yes, there are tools (JavaDoc, Doxygen, etc) which will take specially formatted comments and turn them into standalone documentation. However, in my experience, using those tools did not encourage the sort of documentation you're talking about. The average JavaDoc is an auto-generated stub article that just lists the method name and the names and types of the arguments to the method, which is information my IDE already gives me.
  - TeMPOraL 5y ago
    Counter-counter-counterpoint: if you separate that documentation out, you'll guarantee it getting stale. Good documentation needs low friction - and preferably be part of code review process, so that the reviewer can spot when code changes without updating relevant documentation. Documenting in comments is one way to achieve this, and it also brings two other benefits: - High locality - you're likely to spot the documentation as you read the code it pertains to, because the comments are right there, mixed with the code. - IDE support - interface-level comments are often automatically displayed in autocomplete and hover popups, so you can read them as you browse through suggestions and highlight interesting code fragments.
    - quanticle 5y ago
      > Counter-counter-counterpoint: if you separate that documentation out, you'll guarantee it getting stale. In my experience, having the documentation in the source code has very little effect on whether it gets stale. Unless you make checking for documentation changes an explicit step in the code review, documentation is going to get stale no matter where it is. And if you do have such a step in code review, then it's relatively immaterial whether the documentation is in a wiki or in formatted comments in the source. > High locality - you're likely to spot the documentation as you read the code it pertains to, because the comments are right there, mixed with the code. That actually brings to mind one of my complaints about relying on documentation that's inline with the source code. It's often too local. I can usually read a function and figure out what it's doing. Occasionally, when a function is doing something strange or counterintuitive, some documentation can be helpful, and I definitely acknowledge there's a role for comment-based documentation there. More often, though, I don't want documentation to tell me what this or that function does, I want documentation to show me the big picture. What are all the components of this system? How do they communicate? How does user input propagate? Where does validation occur? These questions are almost never answered by comment-based documentation because of the locality principle that you cite. In addition, the answers to these sorts of questions aren't likely to go out of date. After all, it's not like you're completely rearchitecting how validation works every week (and if you are, documentation is the least of your worries). These sorts of high-level questions are best answered on a wiki or some other tool that supports things like diagrams and well formatted prose text. Yes, in an ideal world, we'd have both. Inline documentation which documents the design at a "micro" level and a wiki or some other knowledge-base which documents the design at a "macro" level. But we don't live in an ideal world. We live in a world where developers are pressed for time, and documentation is most often written after the fact. In this world, I would much rather have the wiki than the inline docs. I can, with a little bit of effort, figure out what each individual function is doing. It's the high-level "how it all fits together" design where I require assistance.
dognotdog 5y ago
> * unit tests are superb documentary as every dev can see how it is used and how it works at runtime. Those unit tests have to be derived from somewhere, though, right? Hopefully, there are requirements docs -- but often those are too high-level, or omit details that were discovered during implementation, and in those cases I'm very appreciative of comments describing intent and purpose of a code snippet or function. Of course, like all things, comments rot without active maintenance and refactoring. In a perfect world, code comments would be redundant, but they do provide a very low-friction way of documenting interesting bits while writing the code, while it takes a lot more effort to back-port information into requirements documentation.
godshatter 5y ago
> * unit tests are superb documentary as every dev can see how it is used and how it works at runtime Unit tests tell me how the code is supposed to behave given certain inputs, but without a statement of what the function is trying to accomplish I can't tell if any necessary unit tests are missing. Or if any are just accidentally working.
- verinus 5y ago
  true. But (hopefully) most of the time good naming, parameters and return types and the context of the library does that. But you are right, esp. complex methods or APIs require lots of documentation- but tbh I doubt it is in sources...

_wp_ 5y ago

I strongly agree with your first two points. Good naming supplants the need for commenting. I find diagrams a far terser communication tool of architecture than comments.

matthiaswh 5y ago
The book has an entire chapter called "Choosing Names" and another titled "Comments Should Describe Things That Aren't Obvious from the Code". Yes, good naming supplants the need for many comments, but the author goes into much greater detail about when and why comments are helpful even when you have given deep consideration into naming things.
- smichel17 5y ago
  I wish we had better tooling for showing the git blame inline like comments. I'd rather put a one line comment "read the commit log for this line" which some editor could inline or pull up quickly than litter the source with prose (but either is better than nothing).
  - TeMPOraL 5y ago
    Except the same belief in "self-documenting code" that makes people ignore the need for comments, also makes them ignore the need for writing proper commit messages. Git blame won't save you, if every commit message is just a one-liner like "fix foo in bar". Viewed from the other end: commit messages are essentially comments over changesets. If you write those well, you can use the same approach to write good comments for your types, functions and modules. See also https://news.ycombinator.com/item?id=27009308 https://news.ycombinator.com/item?id=27009308 on what I consider to be good style of commit messages (scale up or down, depending on the size of your commits).
  - nonameiguess 5y ago
    Some code is intended to last, potentially a very long time, and has to be separable from history metadata. If for no other reason, git trees can get really big. I had a large monorepo at an old job with some code dating back to the mid 80s and it took 10 minutes to clone because of all the history. When we finally gave up on Kiln, years after its own developers abandoned it, we migrated only the code and not the history. After that, you could clone the entire repo in 10 seconds instead of 10 minutes. They key is you want to be able to do something like that without losing crucial information. So anything that absolutely has to be there to understand what code is doing should be directly embedded in the code, that is, it needs to be a comment, not a commit message.

pdamoc 5y ago

Even good software runs in a context. The last commit I did was just to add a comment about a specific ordering in an argument to a function call that had to be that way to compensate for a bug in the library from where the function was imported.

Cthulhu_ 5y ago

Counterpoint: API documentation. I'd rather read a high level overview of a component + its methods than have to open up and read (= decode) the contents, or trudge through the unit tests. If I'm working with it on a lower level then maybe.

quanticle 5y ago
Counter-counterpoint: that documentation should not exist as comments in the code, but as separate, properly formatted documentation. Yes, there are tools (JavaDoc, Doxygen, etc) which will take specially formatted comments and turn them into standalone documentation. However, in my experience, using those tools did not encourage the sort of documentation you're talking about. The average JavaDoc is an auto-generated stub article that just lists the method name and the names and types of the arguments to the method, which is information my IDE already gives me.
- TeMPOraL 5y ago
  Counter-counter-counterpoint: if you separate that documentation out, you'll guarantee it getting stale. Good documentation needs low friction - and preferably be part of code review process, so that the reviewer can spot when code changes without updating relevant documentation. Documenting in comments is one way to achieve this, and it also brings two other benefits: - High locality - you're likely to spot the documentation as you read the code it pertains to, because the comments are right there, mixed with the code. - IDE support - interface-level comments are often automatically displayed in autocomplete and hover popups, so you can read them as you browse through suggestions and highlight interesting code fragments.
  - quanticle 5y ago
    > Counter-counter-counterpoint: if you separate that documentation out, you'll guarantee it getting stale. In my experience, having the documentation in the source code has very little effect on whether it gets stale. Unless you make checking for documentation changes an explicit step in the code review, documentation is going to get stale no matter where it is. And if you do have such a step in code review, then it's relatively immaterial whether the documentation is in a wiki or in formatted comments in the source. > High locality - you're likely to spot the documentation as you read the code it pertains to, because the comments are right there, mixed with the code. That actually brings to mind one of my complaints about relying on documentation that's inline with the source code. It's often too local. I can usually read a function and figure out what it's doing. Occasionally, when a function is doing something strange or counterintuitive, some documentation can be helpful, and I definitely acknowledge there's a role for comment-based documentation there. More often, though, I don't want documentation to tell me what this or that function does, I want documentation to show me the big picture. What are all the components of this system? How do they communicate? How does user input propagate? Where does validation occur? These questions are almost never answered by comment-based documentation because of the locality principle that you cite. In addition, the answers to these sorts of questions aren't likely to go out of date. After all, it's not like you're completely rearchitecting how validation works every week (and if you are, documentation is the least of your worries). These sorts of high-level questions are best answered on a wiki or some other tool that supports things like diagrams and well formatted prose text. Yes, in an ideal world, we'd have both. Inline documentation which documents the design at a "micro" level and a wiki or some other knowledge-base which documents the design at a "macro" level. But we don't live in an ideal world. We live in a world where developers are pressed for time, and documentation is most often written after the fact. In this world, I would much rather have the wiki than the inline docs. I can, with a little bit of effort, figure out what each individual function is doing. It's the high-level "how it all fits together" design where I require assistance.

dognotdog 5y ago

> * unit tests are superb documentary as every dev can see how it is used and how it works at runtime. Those unit tests have to be derived from somewhere, though, right? Hopefully, there are requirements docs -- but often those are too high-level, or omit details that were discovered during implementation, and in those cases I'm very appreciative of comments describing intent and purpose of a code snippet or function. Of course, like all things, comments rot without active maintenance and refactoring. In a perfect world, code comments would be redundant, but they do provide a very low-friction way of documenting interesting bits while writing the code, while it takes a lot more effort to back-port information into requirements documentation.

godshatter 5y ago

> * unit tests are superb documentary as every dev can see how it is used and how it works at runtime Unit tests tell me how the code is supposed to behave given certain inputs, but without a statement of what the function is trying to accomplish I can't tell if any necessary unit tests are missing. Or if any are just accidentally working.

verinus 5y ago
true. But (hopefully) most of the time good naming, parameters and return types and the context of the library does that. But you are right, esp. complex methods or APIs require lots of documentation- but tbh I doubt it is in sources...