5 ms·

>Codes needs "why" comments, not "what" comments. Indeed. While there are exceptions, "what" comments will usually only add noise thus making things more diffi

>Codes needs "why" comments, not "what" comments. Indeed. While there are exceptions, "what" comments will usually only add noise thus making things more difficult. This isn't necessary: // Total count int total_count = 0;

nicoburns 5y ago
I find it's often useful to put a 'what commment' on a block of a few (2-10) lines of code. Then you can skim through the function without reading every individual line of code.
- isbvhodnvemrwvn 5y ago
  You might as well be able to extract a method with a meaningful name then.
  - ziml77 5y ago
    Please no. Don't extract methods methods just to avoid using a comment. You end up making code more difficult to follow when you do that since you're now jumping somewhere else in the file and you're adding a lot of noise by having to pass the function's current state along as arguments to the new function.
    - hackinthebochs 5y ago
      >by having to pass the function's current state along as arguments to the new function. But then the state being read and mutated by a block of code is explicit. The alternative is having to inspect the code to determine if and what state is being manipulated. The more code in a functional unit, the harder this gets.
      - nicoburns 5y ago
        If you're mutating variables then I'd agree that it might be best to encapsulate that in a function. But I'd argue that except for performance sensitive code, that's bad practice. The vast majority of code I write has 95% immutable variables. So even in a large function they'll typically be at most one or two mutable variables to keep track of (and very often zero).
  - nicoburns 5y ago
    That then makes the code non-linear, which IMO makes it a lot less readable in most circumstances.
    - isbvhodnvemrwvn 5y ago
      It depends, if it needed a comment in the first place it likely was at a different (likely lower) level of abstraction than the rest of the code in that method.
      - nicoburns 5y ago
        Yes, but that doesn't mean it doesn't benefit from being inline. I love being able to skim over the paragraph-comments to get the big picture and then dip into the details without having to jump to another file / part of the file and lose my context.
- firebaze 5y ago
  To me it's actually faster and easier to read code instead. This is because i generally don't trust "what" comments - either I know the code already or I don't, and if I don't, then I don't trust the "what" comment fully, so I both have to parse "what" and code. A "why" comment usually ages well, so I generally trust it and can use it to better parse the code and its intentions. So I belong in the "what only for API methods" camp.
  - nicoburns 5y ago
    Do you also read through every function call (at least the first time you encounter a given function)?
- bostonsre 5y ago
  I do something like this, but I write them as debug log statements so that you get the additional benefits from logging.
  - nicoburns 5y ago
    Yes, I've also done this in places. It works pretty well, although I wish I could get my syntax highlighter to de-emphasise these lines like it does with comments.
- majewsky 5y ago
  This is Damian Conway's "coding in paragraphs" advice, and in my experience, it's the single best advice for more readable code. When you have a large function, split the code into blocks with a heading comment on each section. That way, you can skim through the function body quickly by just reading the headings, then dive deeper into whatever block you're interested in. Like section headings on an article.
jbay808 5y ago
What would be your opinion of this comment, though? // Reset the counter for the next run total_count = 0;
- latchkey 5y ago
  why are you resetting the counter?
  - dlp211 5y ago
    For the next run. Why is in the comment, it's likely a design flaw though and no comment is going to help here. See comment about using proper scoping.
- rrose 5y ago
  it feels like this suggests a design flaw. You should probably be creating a new local `total_count` variable for each run that goes out of scope at the end of the run, rather than reusing the same variable over and over again in different contexts
  - wongarsu 5y ago
    // reuse counter for performance, this brings 2% speedup total_count = 0; would be a quite useful why comment, if not creating a new variable each time is intentional
    - rrose 5y ago
      sure, but reusing an integer variable is never going to bring a 2% speedup. allocating a new variable of almost any type is not going to cause any performance issues, at least if it is allocated on the stack, and if the construction of the variable is particularly expensive, resetting it probably will be too. I would need to see a realistic example to believe that something like this would ever be a useful comment.
      - 5y ago

nicoburns 5y ago

I find it's often useful to put a 'what commment' on a block of a few (2-10) lines of code. Then you can skim through the function without reading every individual line of code.

isbvhodnvemrwvn 5y ago
You might as well be able to extract a method with a meaningful name then.
- ziml77 5y ago
  Please no. Don't extract methods methods just to avoid using a comment. You end up making code more difficult to follow when you do that since you're now jumping somewhere else in the file and you're adding a lot of noise by having to pass the function's current state along as arguments to the new function.
  - hackinthebochs 5y ago
    >by having to pass the function's current state along as arguments to the new function. But then the state being read and mutated by a block of code is explicit. The alternative is having to inspect the code to determine if and what state is being manipulated. The more code in a functional unit, the harder this gets.
    - nicoburns 5y ago
      If you're mutating variables then I'd agree that it might be best to encapsulate that in a function. But I'd argue that except for performance sensitive code, that's bad practice. The vast majority of code I write has 95% immutable variables. So even in a large function they'll typically be at most one or two mutable variables to keep track of (and very often zero).
- nicoburns 5y ago
  That then makes the code non-linear, which IMO makes it a lot less readable in most circumstances.
  - isbvhodnvemrwvn 5y ago
    It depends, if it needed a comment in the first place it likely was at a different (likely lower) level of abstraction than the rest of the code in that method.
    - nicoburns 5y ago
      Yes, but that doesn't mean it doesn't benefit from being inline. I love being able to skim over the paragraph-comments to get the big picture and then dip into the details without having to jump to another file / part of the file and lose my context.
firebaze 5y ago
To me it's actually faster and easier to read code instead. This is because i generally don't trust "what" comments - either I know the code already or I don't, and if I don't, then I don't trust the "what" comment fully, so I both have to parse "what" and code. A "why" comment usually ages well, so I generally trust it and can use it to better parse the code and its intentions. So I belong in the "what only for API methods" camp.
- nicoburns 5y ago
  Do you also read through every function call (at least the first time you encounter a given function)?
bostonsre 5y ago
I do something like this, but I write them as debug log statements so that you get the additional benefits from logging.
- nicoburns 5y ago
  Yes, I've also done this in places. It works pretty well, although I wish I could get my syntax highlighter to de-emphasise these lines like it does with comments.
majewsky 5y ago
This is Damian Conway's "coding in paragraphs" advice, and in my experience, it's the single best advice for more readable code. When you have a large function, split the code into blocks with a heading comment on each section. That way, you can skim through the function body quickly by just reading the headings, then dive deeper into whatever block you're interested in. Like section headings on an article.

jbay808 5y ago

What would be your opinion of this comment, though? // Reset the counter for the next run total_count = 0;

latchkey 5y ago
why are you resetting the counter?
- dlp211 5y ago
  For the next run. Why is in the comment, it's likely a design flaw though and no comment is going to help here. See comment about using proper scoping.
rrose 5y ago
it feels like this suggests a design flaw. You should probably be creating a new local `total_count` variable for each run that goes out of scope at the end of the run, rather than reusing the same variable over and over again in different contexts
- wongarsu 5y ago
  // reuse counter for performance, this brings 2% speedup total_count = 0; would be a quite useful why comment, if not creating a new variable each time is intentional
  - rrose 5y ago
    sure, but reusing an integer variable is never going to bring a 2% speedup. allocating a new variable of almost any type is not going to cause any performance issues, at least if it is allocated on the stack, and if the construction of the variable is particularly expensive, resetting it probably will be too. I would need to see a realistic example to believe that something like this would ever be a useful comment.
    - 5y ago