4 ms·
That's exactly what I do. Why is a lot more important that what. Here's an example I use (Verbatim from here[0]): - Why Vs. What I’ve come to realize that
by ChrisMarshallNY 6y ago
That's exactly what I do.
Why is a lot more important that what.
Here's an example I use (Verbatim from here[0]):
-
Why Vs. What
I’ve come to realize that the most important inline documentation concerns WHY we are doing something; not WHAT we are doing.
For example, no one wants to read “// Set the value of b to 3,” for a line of code that looks like let b = 3. That’s just dumb.
let b = 3 // Set the value of b to 3
However, they may want to know “// Set the value of b to the number of iterations we'll be making.”
let b = 3 // Set the value of b to the number of iterations we'll be making
-
[0] https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c8014 https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c...
- ekimekim 6y agoOr perhaps even better: let iterations = 3 // We need to iterate 3 times for the value to stabilize
- thdrdt 6y agoYes, I think your example is better because "// Set the value of b to the number of iterations we'll be making" is almost the same as "/ Set the value of b to 3" when the code explains that `b` is used for the iterations.
- ChrisMarshallNY 6y agoI actually take it forward a bit more in that article, to where clear naming eliminates the need for a comment at all: - With a good name, we could probably do away with the comment entirely: let numberOfIterations = 3 - It’s a fairly exhaustive article (but kind of a long read). Documentation is an important topic. https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c8014 https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c...