Code only says what it does

Re:Code only says what it does by ChrisMarshallNY on Monday July 06, 2020 @08:08PM (#23754240)

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-1c2ddb0c...

[ Parent | on HN ]

Re:Code only says what it does by ekimekim on Tuesday July 07, 2020 @04:32AM (#23756954)

Or perhaps even better:

let iterations = 3 // We need to iterate 3 times for the value to stabilize

[ Parent | on HN ]

Re:Code only says what it does by thdrdt on Tuesday July 07, 2020 @04:51AM (#23757051)

Yes, 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.

[ Parent | on HN ]

Re:Code only says what it does by ChrisMarshallNY on Tuesday July 07, 2020 @05:11AM (#23757164)

I 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-1c2ddb0c...

[ Parent | on HN ]