3 ms·

I think that’s fine as a choice for a personal project, especially since your committed to it. It’s a totally different story when working with a team though. C

I think that’s fine as a choice for a personal project, especially since your committed to it. It’s a totally different story when working with a team though. Comments become outdated, files get larger, and it becomes more of a hassle to maintain while providing little to no value most of the time.

christophilus 8y ago
Comments becoming stale is a real problem. But it is one that is solved by code review and culture, not by fewer comments. In a team setting, comments like these are even more important, as it gives context and higher level meaning to the code without forcing you to jump all over the place through small functions (which would be an alternative way to make this self documenting.
- bwilliams 8y ago
  > comments like these I strongly disagree specifically about comments like these throughout an active code base. A well named variable or method can act as a much better descriptor of what’s happening and doesn’t have the same maintenance cost. I think we both agree that comments are valuable, just not the scope. Comments are valuable when you’re doing something unexpected or where the code fails to explain what’s happening. For what it’s worth I mostly work with Ruby, JavaScript, and TypeScript which definitely color my views.
- jrochkind1 8y ago
  > Comments becoming stale is a real problem. But it is one that is solved by code review and culture, not by fewer comments. Well, it can be both. Less code is easier to maintain than more code, and that applies to comments too. Finding the "goldilocks" point is the challenge of much code design, and it applies to comments too. There's such a thing as both more comments than you need (increasing maintenance cost and risk of outdated comments without providing enough value to justify), as well as less comments than you need (to decrease cost of understanding the codebase).

christophilus 8y ago

Comments becoming stale is a real problem. But it is one that is solved by code review and culture, not by fewer comments. In a team setting, comments like these are even more important, as it gives context and higher level meaning to the code without forcing you to jump all over the place through small functions (which would be an alternative way to make this self documenting.

bwilliams 8y ago
> comments like these I strongly disagree specifically about comments like these throughout an active code base. A well named variable or method can act as a much better descriptor of what’s happening and doesn’t have the same maintenance cost. I think we both agree that comments are valuable, just not the scope. Comments are valuable when you’re doing something unexpected or where the code fails to explain what’s happening. For what it’s worth I mostly work with Ruby, JavaScript, and TypeScript which definitely color my views.
jrochkind1 8y ago
> Comments becoming stale is a real problem. But it is one that is solved by code review and culture, not by fewer comments. Well, it can be both. Less code is easier to maintain than more code, and that applies to comments too. Finding the "goldilocks" point is the challenge of much code design, and it applies to comments too. There's such a thing as both more comments than you need (increasing maintenance cost and risk of outdated comments without providing enough value to justify), as well as less comments than you need (to decrease cost of understanding the codebase).