4 ms·

"Only if you are tracing down a problem you are required to look into the details." This is the common justification, and it's misguided. It turns out that you

"Only if you are tracing down a problem you are required to look into the details." This is the common justification, and it's misguided. It turns out that you need to be aware of the "details" every time you look at the code. If, by looking at the code enough, you memorize the "details," it's tempting to move them to a new function with a clever name that tickles your memory. That won't help anyone else. Use comments to introduce blocks of code that need explaining. Use functions in coherent APIs.

dragonwriter 7y ago
> This is the common justification, and it's misguided. It turns out that you need to be aware of the "details" every time you look at the code. No, I don't. I need to be aware of the relevant details, but code in functions with meaningful names mean (1) I can skim a high level overview to see where the details relative to my current interest we likely to be faster and, (2).I can zoom in without distraction to those more easily. > Use comments to introduce blocks of code that need explaining. Comments make a wall of code that is already hard to get an overview of because of its size less legible, decomposition did the opposite.
- nicoburns 7y ago
  Disagree. Comments can add "section headers", while keeping the code flow linear, so I can skim it just like I skim an article. With methods, I have to jump backwards and forwards and have to remember my place as well as think about the code. This introduces unnecessary overhead.
  - christophilus 7y ago
    I’m with you 100%, but I suspect that we’re a minority. For me, linearity of code is directly proportional to legibility of code. It’s not clear to me whether or not this is universally true, or whether this is an individual preference.
    - networkimprov 7y ago
      Minority, maybe not. There's 20+ upvotes on my original comment re single-caller functions -- much more than replies contradicting it.
  - dragonwriter 7y ago
    > Comments can add "section headers", while keeping the code flow linear, so I can skim it just like I skim an article. Yes, and decomposition provides an outline, which is faster to skim than an article. There's a reason tables of contents are a thing; they let you find wheat you care about much faster than linear text with section headers. With code, they also have the advantage of allowing you to make use of step-over/step-into debugging.

dragonwriter 7y ago

> This is the common justification, and it's misguided. It turns out that you need to be aware of the "details" every time you look at the code. No, I don't. I need to be aware of the relevant details, but code in functions with meaningful names mean (1) I can skim a high level overview to see where the details relative to my current interest we likely to be faster and, (2).I can zoom in without distraction to those more easily. > Use comments to introduce blocks of code that need explaining. Comments make a wall of code that is already hard to get an overview of because of its size less legible, decomposition did the opposite.

nicoburns 7y ago
Disagree. Comments can add "section headers", while keeping the code flow linear, so I can skim it just like I skim an article. With methods, I have to jump backwards and forwards and have to remember my place as well as think about the code. This introduces unnecessary overhead.
- christophilus 7y ago
  I’m with you 100%, but I suspect that we’re a minority. For me, linearity of code is directly proportional to legibility of code. It’s not clear to me whether or not this is universally true, or whether this is an individual preference.
  - networkimprov 7y ago
    Minority, maybe not. There's 20+ upvotes on my original comment re single-caller functions -- much more than replies contradicting it.
- dragonwriter 7y ago
  > Comments can add "section headers", while keeping the code flow linear, so I can skim it just like I skim an article. Yes, and decomposition provides an outline, which is faster to skim than an article. There's a reason tables of contents are a thing; they let you find wheat you care about much faster than linear text with section headers. With code, they also have the advantage of allowing you to make use of step-over/step-into debugging.