Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Writing Well-Documented Code – Learn from Examples

codecatalog.org

Post reply on HN
Print view View original

21–30 of 153 posts

Re: Writing Well-Documented Code – Learn from Examples

#21

Post by ainzzorl »

Fire-Dragon-DoL wrote: post #3

The first has an enormous amount of visual noise and it's definitely over commented. The second one is ok, but please don't follow the first one as a good example, it takes away the ability to scan the code

I agree that some comments in the first example are unnecessary, e.g. the one pointed out in [0], but I find comments like that at worst useless, but not harmful. They have a potential to become harmful if someone updates the code but doesn't bother to update the comment, but I can't see how it takes away the ability to scan the code.

[0]: https://news.ycombinator.com/item?id=28416777

Re: Writing Well-Documented Code – Learn from Examples

#22

Post by kyleee »

ReactiveJelly wrote: post #15
cpach wrote: post #13

Earlier quoted context omitted.

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 trustin…

Let's hear more about your threat model that causes you to wory about nefarious content being injected into a blog post about comments in code

Re: Writing Well-Documented Code – Learn from Examples

#23

Post by kyleee »

komon wrote: post #12
achenatx wrote: post #5

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

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

#25

Post by ainzzorl »

mibollma wrote: post #2

I like the idea of codecatalog. Would be nice to see some functional Kotlin examples that go beyond list processing.

Thanks! If you know some good examples, please consider proposing them: https://github.com/ainzzorl/goodcode/issues/new?assignees=&l...

Re: Writing Well-Documented Code – Learn from Examples

#26

Post by codethief »

ReactiveJelly wrote: post #15
cpach wrote: post #13

Earlier quoted context omitted.

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 trustin…

Wow, you just opened my eyes – I really thought he had deleted his blog! Must be the HTTPS Everywhere extension I'm using – though I really don't understand why it redirects me to redis.io just because antirez's TLS certificate is for redis.io, not antirez.com. I would really prefer a clear error message here.

Re: Writing Well-Documented Code – Learn from Examples

#27

Post by [deleted] »

achenatx wrote: post #5

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 limitin…

[deleted]

Re: Writing Well-Documented Code – Learn from Examples

#28

Post by bcyn »

komon wrote: post #12
achenatx wrote: post #5

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

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

#29

Post by Lio »

ainzzorl wrote: post #21
Fire-Dragon-DoL wrote: post #3

The first has an enormous amount of visual noise and it's definitely over commented. The second one is ok, but please don't follow the first one as a good example, it takes away the ability to scan the code

I agree that some comments in the first example are unnecessary, e.g. the one pointed out in [0], but I find comments like that at worst useless, but not harmful. They have a potential to become harmful if someone updates the code but doesn't bother to update the comment, but I can't see how it takes away the ability to scan the code. [0]: https://news.ycombinator.com/item?id=28416777

It’s tricky, I think I remember reading a paper by Microsoft research (I’m really sorry; looking for a source) that showed a correlation between bugs and all lines of code including comments.

So if that’s true redundant comments do hurt you.

Anecdotally in dynamic languages incorrect comments related to types seem to be a constant pain for me. They’re unverified and so a second source of truth that often wrong and can’t be trusted.

Re: Writing Well-Documented Code – Learn from Examples

#30

Post by ainzzorl »

codethief wrote: post #9
Fire-Dragon-DoL wrote: post #3

The first has an enormous amount of visual noise and it's definitely over commented. The second one is ok, but please don't follow the first one as a good example, it takes away the ability to scan the code

> The second one is ok, but please don't follow the first one as a good example, it takes away the ability to scan the code. IMO if at all, this type of comment ("Why was X designed this way") should go to the very bottom of the file (maybe with a very short comment at the top of the file referencing it), so it doesn't bother anyone who works on the code on a regular basis. And one could (should) also decrease its ve…

A lot of code files starts with lengthy copyright notices, and no one seems to mind. I find comments at the top very easy to ignore if I work on that code regularly. Also, I don't think I've ever seen comments at the bottom of a file!

I wonder if Protobuf wasn't open-sourced by Google, that comment would've been replaced with a link to a design doc. Google docs weren't a thing in early 2000s when Protobuf was originally written though.

Post reply on HN