I have a simple rule to go by. Comments should describe “why” and the code should describe “what”.
Writing Well-Documented Code – Learn from Examples
11–20 of 153 posts
Re: Writing Well-Documented Code – Learn from Examples
#12some 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 limitin…
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
#13Speaking of source code comments, antirez (of Redis fame) wrote a fantastic article[0] about that topic some time ago and I still recommend it to colleagues whenever they make the hollow statement that "code should and can be intelligible on its own, without any comments". [0]: https://web.archive.org/web/20210226004600/http://antirez.co... (I still don't understand why he deleted his blog)
Huh? That URL is still alive: http://antirez.com/news/124
Re: Writing Well-Documented Code – Learn from Examples
#14Speaking of source code comments, antirez (of Redis fame) wrote a fantastic article[0] about that topic some time ago and I still recommend it to colleagues whenever they make the hollow statement that "code should and can be intelligible on its own, without any comments". [0]: https://web.archive.org/web/20210226004600/http://antirez.co... (I still don't understand why he deleted his blog)
Huh? That URL is still alive: http://antirez.com/news/124
Huh? I've been getting
> Sorry, I can't find that page :-/
for several months
Re: Writing Well-Documented Code – Learn from Examples
#15Speaking of source code comments, antirez (of Redis fame) wrote a fantastic article[0] about that topic some time ago and I still recommend it to colleagues whenever they make the hollow statement that "code should and can be intelligible on its own, without any comments". [0]: https://web.archive.org/web/20210226004600/http://antirez.co... (I still don't understand why he deleted his blog)
Huh? That URL is still alive: http://antirez.com/news/124
Maybe it's a buggy HTTPS redirect in GP's browser? Due to HSTS or something?
The HTTP version of your URL works fine. The HTTPS version has an expired cert. If I click past that, it redirects to redis.io, then gives a 404.
I know antirez is a smart guy, but if this is some kind of "I'm taking a bold stance against HTTPS" then I'd rather read the archive.org link with functioning HTTPS. My threat model prefers trusting archive.org to correctly reproduce the blog, over trusting everyone between me and antirez.com.
Re: Writing Well-Documented Code – Learn from Examples
#16Re: Writing Well-Documented Code – Learn from Examples
#17Way to much
Re: Writing Well-Documented Code – Learn from Examples
#18I just prefer nice, long, descriptive function names.
I was working on an unfamiliar codebase yesterday and had to work with the postMessage function. It was React, so one might assume that it sends the message to the backend, which was my initial assumption. Nope. It posted it to the page. Didn't help that another utility had another postMessage that was about what to do after the message was sent.
Re: Writing Well-Documented Code – Learn from Examples
#19I wish there was an option for dark mode or something.
Re: Writing Well-Documented Code – Learn from Examples
#20I just prefer nice, long, descriptive function names. I was working on an unfamiliar codebase yesterday and had to work with the postMessage function. It was React, so one might assume that it sends the message to the backend, which was my initial assumption. Nope. It posted it to the page. Didn't help that another utility had another postMessage that was about what to do after the message was sent.
I worked with a guy who wrote a CPU simulator and exceeded the MSVC 256-char function name limit. It's hard when you like 80/100 col code and a function name is longer than that.