3 ms·

I'd rather call that 'how' instead of 'what', because there are two things you might take "what does this code do?" to mean: its purpose or the way it works. A

I'd rather call that 'how' instead of 'what', because there are two things you might take "what does this code do?" to mean: its purpose or the way it works. A square-root function, for example, might have How: newton-raphson iteration, 2 rounds What: return a number within 1% of the positive square root of the input, which must be in a certain range Why: it's for a rendering, it doesn't need to be precise In this breakdown the 'what' is what I tend to want the most often, as a reader. It gives an anchor to check the code against, and enables reading that code without having to understand all the other code it calls on -- just the 'what' comments of the other code.

AstralStorm 10y ago
Why is the more important one - it is the requirement. I'd rather see something like this: Why: We need to calculate distances between widgets to pack them so that it looks nice to the end user, but is also fast - start must not take longer than about 1 second. We are running on embedded hardware. What: Use square root approximation for distance defined over the range of pixels available on screen. How: Newton-raphson iteration, 2 rounds, fixed point.
- abecedarius 10y ago
  Fair enough -- I mainly wanted to point out an important distinction blurred by "why vs. what". It's up to the context whether you'd care more about this kind of why or what. However, it's this what -- what the code is meant to do -- that's both the most basic info for maintenance and in poorer supply, as I've seen it. It's often easier to get an off-the-cuff answer to "why do that?" (or to not need it) than "exactly what was this code meant to do? Does the rest of the system depend on the fact that it freems the bleetches, or can I change that?" -- in that case you're more likely to get back "Hm, I'd better read all this related code to swap it into my head". Your experience might be different, and that'd be kind of interesting.

AstralStorm 10y ago

Why is the more important one - it is the requirement. I'd rather see something like this: Why: We need to calculate distances between widgets to pack them so that it looks nice to the end user, but is also fast - start must not take longer than about 1 second. We are running on embedded hardware. What: Use square root approximation for distance defined over the range of pixels available on screen. How: Newton-raphson iteration, 2 rounds, fixed point.

abecedarius 10y ago
Fair enough -- I mainly wanted to point out an important distinction blurred by "why vs. what". It's up to the context whether you'd care more about this kind of why or what. However, it's this what -- what the code is meant to do -- that's both the most basic info for maintenance and in poorer supply, as I've seen it. It's often easier to get an off-the-cuff answer to "why do that?" (or to not need it) than "exactly what was this code meant to do? Does the rest of the system depend on the fact that it freems the bleetches, or can I change that?" -- in that case you're more likely to get back "Hm, I'd better read all this related code to swap it into my head". Your experience might be different, and that'd be kind of interesting.