Re:Attitudes That Lead to Maintainable Code
by AstralStorm on Thursday March 09, 2017 @07:11AM
(#13828728)
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.
Re:Attitudes That Lead to Maintainable Code
by abecedarius on Thursday March 09, 2017 @06:53PM
(#13835021)
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.
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.