News for hackers. Stuff that matters.
Re:Writing Well-Documented Code – Learn from Examples by didip on Saturday September 04, 2021 @01:11PM (#28416874)
I have a simple rule to go by. Comments should describe “why” and the code should describe “what”.
Re:Writing Well-Documented Code – Learn from Examples by ainzzorl on Saturday September 04, 2021 @02:17PM (#28417638)
While I agree with the general sentiment, the first example in the article IMO demonstrates how "what" comments make understanding code easier. When I first read that code, I was pleasantly surprised how easy it was to understand everything going on there, even though I had no familiarity with the code base. This is rare for non-trivial projects. I'm not sure if it could be made as clear without those comments.
Re:Writing Well-Documented Code – Learn from Examples by Rapzid on Saturday September 04, 2021 @04:20PM (#28418725)
Agree; could be very helpful if somebody not fam with token buckets arrives at this code for some reason and needs to make sense of it. Also, I think one person's "what" is another person's "why":

> if self.one_time_burst > 0 {

What is this code doing? It's setting up a flow control statement. It's dereferencing the "one_time_burst" property on the object self and comparing the value to 0. If the value is greater than 0, it will execute the proceeding code block.

Why is this being done?

> [to] consume the one-time-burst budget.

Re:Writing Well-Documented Code – Learn from Examples by trinovantes on Saturday September 04, 2021 @05:01PM (#28419157)
"Why not" comments are also very helpful

Self-explanatory code can't explain themselves if they do not exist

Re:Writing Well-Documented Code – Learn from Examples by einpoklum on Saturday September 04, 2021 @05:17PM (#28419314)
I upvoted you, but there are plenty of exceptions. For example:

* Common name of the algorithm you're using

* Reference to somewhere else in the code that's related

* "You may think this code only does X, but it really also does Y"

* "We used to also do XYZ here, but that was removed because of ABC"

and so on.

Re:Writing Well-Documented Code – Learn from Examples by ridiculous_fish on Saturday September 04, 2021 @05:10PM (#28419265)
How do you know what a function does, without a "what" comment to explain it? Even "obvious" functions like Math.max have edge cases, and I rely on "what" comments to understand how those cases are handled.
Re:Writing Well-Documented Code – Learn from Examples by SV_BubbleTime on Saturday September 04, 2021 @03:04PM (#28418058)
WHY comments drastically improved my code.

I’ve similarly been paying much more attention to convey INTENT which I think is massively missing from computer science. The code might suck, but if the intent is clearly defined, it helps to refactor later.

Re:Writing Well-Documented Code – Learn from Examples by ozim on Saturday September 04, 2021 @01:52PM (#28417345)
I agree and first example in the article is all comments describing what the code is doing. There is not a single one explaining why.

Well I stopped reading further.

Re:Writing Well-Documented Code – Learn from Examples by ChrisMarshallNY on Saturday September 04, 2021 @03:15PM (#28418155)
Agreed.

That's what works for me.