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

71–80 of 153 posts

Re: Writing Well-Documented Code – Learn from Examples

#71

Post by codethief »

rgoulter wrote: post #55

Worth comparing: http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.htm... A "n00b" is scared of code, and wants as much help to understand it as possible. An "expert" already knows all they need to know to work on the code, and is more productive by putting as much code on the screen as they can. Rather.. I think part of the point is, context matters. If the team is small, and the project is changing rapidly..…

> an "expert"

Here's the problem: "Experts" (or "veterans" as the author calls them) are not created equal: There's the expert that already knows the code because she's worked on it countless times and already has a very detailed mental model of the code and there's the expert who's a very experienced programmer but has never seen the code before.

Even experts of the latter category appreciate good comments when they read code (surely not comments of the "n00b" kind portrayed in the article but comments nonetheless).

Re: Writing Well-Documented Code – Learn from Examples

#72

Post by [deleted] »

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.

[deleted]

Re: Writing Well-Documented Code – Learn from Examples

#73

Post by Rapzid »

Lio wrote: post #29
ainzzorl wrote: post #21

Earlier quoted context omitted.

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

> correlation

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

Anyway, even if there was causation proven it might need to be weighed against other priorities.

Re: Writing Well-Documented Code – Learn from Examples

#74

Post by Rapzid »

ainzzorl wrote: post #43
didip wrote: post #11

I have a simple rule to go by. Comments should describe “why” and the code should describe “what”.

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.

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

#76

Post by unchar1 »

cratermoon wrote: post #50
abootstrapper wrote: post #35

Earlier quoted context omitted.

I agree with you. Code should be intelligible on its own without comments. It should also be well documented. One does not preclude the other.

I've forgotten who first wrote this, so I can't credit them, but there's a saying that if someone can't write clear, clean, and understandable code , why does anyone expect them to be able to write clear, clean, and understandable English (or whatever language)? It's quite a bit easier to write something the compiler or runtime can understand, there's no need for meaningful names, consistent structure, or conceptual…

I first heard that in a talk by Kevlin Henney [1]. I'm not sure if he's the one who came up with it though.

[1]: https://twitter.com/KevlinHenney/status/381021802941906944

Re: Writing Well-Documented Code – Learn from Examples

#77

Post by nijave »

pcmoney wrote: post #36

Personally I found most of those examples to be not great. I think they would be improved better names overall, more well named private methods and most importantly well structured companion test classes proving the behavior. I really dont want to read another developers comments on their mental state while I am feverishly debugging their code during a 3am page. The number of times I have been misled by an outdated c…

>The number of times I have been misled by an outdated comment

Imo a problem with code review and not leaving comments. Just like tests need changed during refactoring, documentation and comments should also be cleaned up as part of the change

I have found those as well but place the blame on the person who made the subsequent change and ignored them

Re: Writing Well-Documented Code – Learn from Examples

#79

Post by mrathi12 »

pcmoney wrote: post #36

Personally I found most of those examples to be not great. I think they would be improved better names overall, more well named private methods and most importantly well structured companion test classes proving the behavior. I really dont want to read another developers comments on their mental state while I am feverishly debugging their code during a 3am page. The number of times I have been misled by an outdated c…

Agreed, I think that the code itself should be readable through better names, with the comments being a bonus rather than critical to the understanding of the code.
Post reply on HN