News for hackers. Stuff that matters.
Re:Writing Well-Documented Code – Learn from Examples by achenatx on Saturday September 04, 2021 @01:00PM (#28416777)
some types of comments are redundant.

These days I write my code as comments first and then write the code.

But for example this one

        // If either token bucket capacity or refill time is 0, disable limiting.
        if size == 0 || complete_refill_time_ms == 0 {
            return None;
        }
The comment is the same as the code. It is pointless. Instead I might say under what circumstances I expect them to be zero or why Im disabling limiting when they are zero.

This one is great, though at first glance I cant relate the actual code to the comment, at least I understand why the code is there.

            // We still have burst budget for *some* of the tokens requests.
            // The tokens left unfulfilled will be consumed from current `self.budget`.
            tokens -= self.one_time_burst;
            self.one_time_burst = 0;
Re:Writing Well-Documented Code – Learn from Examples by komon on Saturday September 04, 2021 @01:13PM (#28416892)
In defense of the first comment, when first approaching a body of code like this, it's not always going to be clear what returning None is going to mean in any given method.

Also, one thing I think doesn't get mentioned enough is the use of comments as anchors for text search. Having "disable limiting" expressed in English that way makes it easier for newcomers to explore the codebase.

Re:Writing Well-Documented Code – Learn from Examples by kyleee on Saturday September 04, 2021 @01:34PM (#28417121)
Good point. Also the phrases in the initial comment "token bucket capacity" and "refill time" may serve as hints and can be used as entry points to searching external documentation.
Re:Writing Well-Documented Code – Learn from Examples by codethief on Saturday September 04, 2021 @03:27PM (#28418257)
I agree, though I think it would be even better if variables were named "token bucket capacity" and "refill time" in the first place.
Re:Writing Well-Documented Code – Learn from Examples by bcyn on Saturday September 04, 2021 @01:42PM (#28417226)
It’s hard to judge out of context. IMO None meaning “disable limiting” should be a docstring/comment at the method level, describing what its return values mean, not inline next to this code.
Re:Writing Well-Documented Code – Learn from Examples by Zababa on Saturday September 04, 2021 @02:10PM (#28417576)
I don't think the comment is the same as the code. If "size" was called "token_bucket_capacity" I would agree but since it's not, if you remove the comment you lose some context.
Re:Writing Well-Documented Code – Learn from Examples by Koshkin on Saturday September 04, 2021 @05:51PM (#28419634)
> understand why the code is there

You hit the nail on the head here. This is the single most important reason for having comments in code (aside from just being a part of a coding standard).