7 ms·

Personally I found most of those examples to be not great. I think they would be improved better names overall, more well named private methods and most importa

Personally I found most of those examples to be not great. I think they would be improved better names overall, more well named private methods and most importantly well structured companion test classes proving the behavior. I really dont want to read another developers comments on their mental state while I am feverishly debugging their code during a 3am page. The number of times I have been misled by an outdated comment. I generally open git blame to see if the comments predate any code now. Tests on the other hand almost never lie. Readmes or comments explaining why something exists vs what it allegedly does are generally much better. If you can’t write expressive code why would you assume your English is much better?

tempest_ 5y ago
That is how I feel about these comments. In a vacuum I like them and when I bump into a piece of 10 year old code commented like this it is great. There is one caveat however, they have to be meticulously maintained and always updated to reflect every change made to the code. It is a huge caveat because more often than not the comments are out dated and no longer reflect the actual code and at that point they are detrimental.
- coliveira 5y ago
  That's why Knuth had the idea of creating literate programs where documentation and code was maintained in a single block. Unfortunately, this idea was never used in large scale.
  - kevin_thibedeau 5y ago
    Have you ever tried to read the soup he created with code blocks rearranged to suit the generated text rather than any future maintenance coder?
    - RobertKerans 5y ago
      Yeah, I think there's a fundamental problem with the implementation -- with small, single-file programs where the code can be written in a chronologically linear manner it works well. But with that there's no need for reordering logic, so much of the more complex parts of weaving are redundant. Scripts, for example, are pretty easy to set up as [for example] markdown files, which works great (particularly in a project that requires a set of helper scripts which need why communicated -- having a set of markdown files in a folder makes it IME much more ergonomic for other devs). Anything larger and it gets increasingly fiddly and (again IME) not worth it.
nijave 5y ago
>The number of times I have been misled by an outdated comment Imo a problem with code review and not leaving comments. Just like tests need changed during refactoring, documentation and comments should also be cleaned up as part of the change I have found those as well but place the blame on the person who made the subsequent change and ignored them
- oxfeed65261 5y ago
  …and on the reviewer(s) who accepted the code change even though the comments no longer match the code.
  - Gh0stRAT 5y ago
    I agree, but git and most code reviewing tools I've used only show a few lines of surrounding context so the reviewers might not even realize there's a comment further up that needs updating.
    - msbarnett 5y ago
      Generally speaking, for all but the smallest of changes you should never only review the diff, but pop open the actual file on that branch (GitHub makes this fairly easy, I can't speak to other tooling) and consider the change in the context of the surrounding code. Does it contradict comments? Needlessly duplicate code from elsewhere in the file instead of creating a single function to be used in both places? Shadow variables confusingly? Add yet another 5 lines to a 100 line function instead of leaving the code better than it found it? You can't really judge any of this if you're just eyeballing a diff. Diffs are just the starting point for a review, and while tooling could make this easier, the full file is always just a git checkout away.
- prpl 5y ago
  There’s not many code review platforms that are great at showing you relevant comments in a diff because they are often in a much different part of the file, so I kind of think it’s hopeless in a large code base to catch this sort of thing in a code review
mrathi12 5y ago
Agreed, I think that the code itself should be readable through better names, with the comments being a bonus rather than critical to the understanding of the code.
t-3 5y ago
Exactly. In my opinion, Thinking Forth by Leo Brodie should be required reading for anyone who touches code.
AlexCoventry 5y ago
> If you can’t write expressive code why would you assume your English is much better? Because English is optimized for communicating human intent?
- pcmoney 5y ago
  I guess aside from assembly and very low level or highly specified languages aren’t programming languages as well?
  - AlexCoventry 5y ago
    In my experience, it's much easier to get just the right level of abstraction for quick reader comprehension in natural English, compared to any programming language.
omegalulw 5y ago
Yup, the rate limiter comments are unhelpful. A top level comment explaining the idea is fine (and very useful) but code should largely be self documenting.
- axiosgunnar 5y ago
  Which it often is, but they still wrote a comment, leading to ridiculous stuff along the lines of > // Returns None is x = 0 if x = 0 { return None }
SiVal 5y ago
The problem with all discussions of good commenting style is that it's like debating good footware. Good for what? Office? Hiking in snow? Walking on the beach? Except that we have different footware for different uses but only one set of comments. Having such a limited commenting syntax is like assuming one permanent type of footware and debating which one would be best. I'd much rather have a smarter commenting system. I'm not talking about supplementary docs stashed elsewhere to gather dust. I'd like to have expandable comments right where they are needed but usable differently for a glance at familiar code or puzzling through unfamiliar code. Something very brief that doesn't clutter the code, a couple of words or no words at all, with an expansion arrow to something more detailed, expanding to something fully documented with links to everything. And comments with scope (this comment applies to this line, this one to the function, this to a group of functions...) that actively use the scope. By active I mean that if you make any edits to code in the scope of a comment, that comment changes color or some other mechanism similar to a Git merge conflict: You changed the code without changing the comment, so check and make sure the comment says what you want and click OK. You don't have to fix the comments immediately for each edit. Make a few changes, test, make sure it's working, but when it is, you can see at a glance which comments need to be checked. The general idea is instead of debating The Best Way to Comment, consider ways to improve the commenting system itself.
- x-shadowban 5y ago
  Inline graphviz annotations would be very nice. Store the text, IDE "codelens" renders it out
- seanwilson 5y ago
  > (this comment applies to this line, this one to the function, this to a group of functions...) This is probably the major reason I much prefer introducing new variables and functions solely so I can give them descriptive names over using comments. Comments aren't scoped so they're often ambiguous and imprecise compared to code, which also contributes to them becoming out-of-sync with the code over time. Comments above a function definition are generally better than comments inside a function for example as it's clearer what the scope is.
chris_wot 5y ago
I have to agree. Unit tests are some of the most helpful things I’ve used whilst refactoring the Libreoffice vcl module. In fact, I’m now at the stage where if I only move a class into a new header I’m writing a test that covers that class. An example I’m currently working on is: https://gerrit.libreoffice.org/c/core/+/121403/5/vcl/qa/cppunit/printer/optionshelper.cxx https://gerrit.libreoffice.org/c/core/+/121403/5/vcl/qa/cppu...
tpoacher 5y ago
To me, comments in code are like descriptions in a novel. I would agree that comments which unnecessarily describe what is to come are bad, in the same way that a novelist should prefer to show, not tell, unless there is a compelling reason for the reader to keep that description in mind as the immediate events unfold. But to require almost all comments gone in favour of well-named code and external docs feels wrong too, in the same way that one would probably not like to read a book with no chapter headings, no visuals, simply describing the story in a dry (but informative) language, and relying on cliffnotes for actual context. And if you say code is more like a technical report than a novel, I will disagree. Good code is always a pleasure to read, and typically for similar reasons that a good novel is pleasurable.

tempest_ 5y ago

That is how I feel about these comments. In a vacuum I like them and when I bump into a piece of 10 year old code commented like this it is great. There is one caveat however, they have to be meticulously maintained and always updated to reflect every change made to the code. It is a huge caveat because more often than not the comments are out dated and no longer reflect the actual code and at that point they are detrimental.

coliveira 5y ago
That's why Knuth had the idea of creating literate programs where documentation and code was maintained in a single block. Unfortunately, this idea was never used in large scale.
- kevin_thibedeau 5y ago
  Have you ever tried to read the soup he created with code blocks rearranged to suit the generated text rather than any future maintenance coder?
  - RobertKerans 5y ago
    Yeah, I think there's a fundamental problem with the implementation -- with small, single-file programs where the code can be written in a chronologically linear manner it works well. But with that there's no need for reordering logic, so much of the more complex parts of weaving are redundant. Scripts, for example, are pretty easy to set up as [for example] markdown files, which works great (particularly in a project that requires a set of helper scripts which need why communicated -- having a set of markdown files in a folder makes it IME much more ergonomic for other devs). Anything larger and it gets increasingly fiddly and (again IME) not worth it.

nijave 5y ago

>The number of times I have been misled by an outdated comment Imo a problem with code review and not leaving comments. Just like tests need changed during refactoring, documentation and comments should also be cleaned up as part of the change I have found those as well but place the blame on the person who made the subsequent change and ignored them

oxfeed65261 5y ago
…and on the reviewer(s) who accepted the code change even though the comments no longer match the code.
- Gh0stRAT 5y ago
  I agree, but git and most code reviewing tools I've used only show a few lines of surrounding context so the reviewers might not even realize there's a comment further up that needs updating.
  - msbarnett 5y ago
    Generally speaking, for all but the smallest of changes you should never only review the diff, but pop open the actual file on that branch (GitHub makes this fairly easy, I can't speak to other tooling) and consider the change in the context of the surrounding code. Does it contradict comments? Needlessly duplicate code from elsewhere in the file instead of creating a single function to be used in both places? Shadow variables confusingly? Add yet another 5 lines to a 100 line function instead of leaving the code better than it found it? You can't really judge any of this if you're just eyeballing a diff. Diffs are just the starting point for a review, and while tooling could make this easier, the full file is always just a git checkout away.
prpl 5y ago
There’s not many code review platforms that are great at showing you relevant comments in a diff because they are often in a much different part of the file, so I kind of think it’s hopeless in a large code base to catch this sort of thing in a code review

mrathi12 5y ago

Agreed, I think that the code itself should be readable through better names, with the comments being a bonus rather than critical to the understanding of the code.

t-3 5y ago

Exactly. In my opinion, Thinking Forth by Leo Brodie should be required reading for anyone who touches code.

AlexCoventry 5y ago

> If you can’t write expressive code why would you assume your English is much better? Because English is optimized for communicating human intent?

pcmoney 5y ago
I guess aside from assembly and very low level or highly specified languages aren’t programming languages as well?
- AlexCoventry 5y ago
  In my experience, it's much easier to get just the right level of abstraction for quick reader comprehension in natural English, compared to any programming language.

omegalulw 5y ago

Yup, the rate limiter comments are unhelpful. A top level comment explaining the idea is fine (and very useful) but code should largely be self documenting.

axiosgunnar 5y ago
Which it often is, but they still wrote a comment, leading to ridiculous stuff along the lines of > // Returns None is x = 0 if x = 0 { return None }

SiVal 5y ago

The problem with all discussions of good commenting style is that it's like debating good footware. Good for what? Office? Hiking in snow? Walking on the beach? Except that we have different footware for different uses but only one set of comments. Having such a limited commenting syntax is like assuming one permanent type of footware and debating which one would be best. I'd much rather have a smarter commenting system. I'm not talking about supplementary docs stashed elsewhere to gather dust. I'd like to have expandable comments right where they are needed but usable differently for a glance at familiar code or puzzling through unfamiliar code. Something very brief that doesn't clutter the code, a couple of words or no words at all, with an expansion arrow to something more detailed, expanding to something fully documented with links to everything. And comments with scope (this comment applies to this line, this one to the function, this to a group of functions...) that actively use the scope. By active I mean that if you make any edits to code in the scope of a comment, that comment changes color or some other mechanism similar to a Git merge conflict: You changed the code without changing the comment, so check and make sure the comment says what you want and click OK. You don't have to fix the comments immediately for each edit. Make a few changes, test, make sure it's working, but when it is, you can see at a glance which comments need to be checked. The general idea is instead of debating The Best Way to Comment, consider ways to improve the commenting system itself.

x-shadowban 5y ago
Inline graphviz annotations would be very nice. Store the text, IDE "codelens" renders it out
seanwilson 5y ago
> (this comment applies to this line, this one to the function, this to a group of functions...) This is probably the major reason I much prefer introducing new variables and functions solely so I can give them descriptive names over using comments. Comments aren't scoped so they're often ambiguous and imprecise compared to code, which also contributes to them becoming out-of-sync with the code over time. Comments above a function definition are generally better than comments inside a function for example as it's clearer what the scope is.

chris_wot 5y ago

I have to agree. Unit tests are some of the most helpful things I’ve used whilst refactoring the Libreoffice vcl module. In fact, I’m now at the stage where if I only move a class into a new header I’m writing a test that covers that class. An example I’m currently working on is: https://gerrit.libreoffice.org/c/core/+/121403/5/vcl/qa/cppunit/printer/optionshelper.cxx https://gerrit.libreoffice.org/c/core/+/121403/5/vcl/qa/cppu...

tpoacher 5y ago

To me, comments in code are like descriptions in a novel. I would agree that comments which unnecessarily describe what is to come are bad, in the same way that a novelist should prefer to show, not tell, unless there is a compelling reason for the reader to keep that description in mind as the immediate events unfold. But to require almost all comments gone in favour of well-named code and external docs feels wrong too, in the same way that one would probably not like to read a book with no chapter headings, no visuals, simply describing the story in a dry (but informative) language, and relying on cliffnotes for actual context. And if you say code is more like a technical report than a novel, I will disagree. Good code is always a pleasure to read, and typically for similar reasons that a good novel is pleasurable.