4 ms·

I often write comments before I write the code as it helps me think it out. Then I leave the comments there even when they are not necessarily highlighting crit

I often write comments before I write the code as it helps me think it out. Then I leave the comments there even when they are not necessarily highlighting critical points. Often I find them a useful reminder later on. I don't think I've ever looked at some code and thought I wish there were less comments. I don't see why comments have such a lowly status. Of course you can tell when someone wrote a comment because they felt they HAD to...stuff like: /* Adding one to X */ x = x + 1 Which I've actually seen...but anything even remotely intelligent is generally welcome, I think.

hnlmorg 7y ago
Honestly, I find those kind of comment more distracting than useful. I once read somewhere that comments should explain the reason rather than the action. For example: /* x is taken from a system counter but it needs to be consumed by humans. So we add 1 because humans don't count from zero */ x = x + 1 is a more useful comment.
- colatkinson 7y ago
  Yeah I definitely agree with this. If I'm incrementing x in such a way that it's pretty clear what the meaning is (e.g. it's actually called like cur_page or something and I'm iterating over paginated data), then comments don't add a lot of value. Especially if they're not actually kept up to date with code changes. On the other hand, comments like, "Hey don't change this because if you do, it'll break things in subtle and hard to test way because x," are definitely useful.
- lozenge 7y ago
  but pageCountDisplayed = pageCount + 1 is more useful still.
  - hnlmorg 7y ago
    In that specific case, potentially - bare in mind it's imaginary code you're refactoring. There will be occasions when "ugly" code is required. The point of my post, which I suspect you missed, is that comments will generally be more useful if they describe the purpose of that code (which is harder to deduce) rather than what that code does (which often can be easily deduced just be reading the code).
    - lozenge 7y ago
      The point of my post is that code will be more useful if it describes the purpose of that code. Sure, for the rest of the time there's comments.
      - hnlmorg 7y ago
        Yes, I got that. As I said: > In that specific case, potentially - bare in mind it's imaginary code you're refactoring. There will be occasions when "ugly" code is required. ie, I don't disagree with your point however it's not always possible to refactor code for readability. Plus you're still missing the point that writing better comments can give you additional information ("why does it do it") that you might not gleam even from even well written code ("what does it do").

hnlmorg 7y ago

Honestly, I find those kind of comment more distracting than useful. I once read somewhere that comments should explain the reason rather than the action. For example: /* x is taken from a system counter but it needs to be consumed by humans. So we add 1 because humans don't count from zero */ x = x + 1 is a more useful comment.

colatkinson 7y ago
Yeah I definitely agree with this. If I'm incrementing x in such a way that it's pretty clear what the meaning is (e.g. it's actually called like cur_page or something and I'm iterating over paginated data), then comments don't add a lot of value. Especially if they're not actually kept up to date with code changes. On the other hand, comments like, "Hey don't change this because if you do, it'll break things in subtle and hard to test way because x," are definitely useful.
lozenge 7y ago
but pageCountDisplayed = pageCount + 1 is more useful still.
- hnlmorg 7y ago
  In that specific case, potentially - bare in mind it's imaginary code you're refactoring. There will be occasions when "ugly" code is required. The point of my post, which I suspect you missed, is that comments will generally be more useful if they describe the purpose of that code (which is harder to deduce) rather than what that code does (which often can be easily deduced just be reading the code).
  - lozenge 7y ago
    The point of my post is that code will be more useful if it describes the purpose of that code. Sure, for the rest of the time there's comments.
    - hnlmorg 7y ago
      Yes, I got that. As I said: > In that specific case, potentially - bare in mind it's imaginary code you're refactoring. There will be occasions when "ugly" code is required. ie, I don't disagree with your point however it's not always possible to refactor code for readability. Plus you're still missing the point that writing better comments can give you additional information ("why does it do it") that you might not gleam even from even well written code ("what does it do").