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

61–70 of 153 posts

Re: Writing Well-Documented Code – Learn from Examples

#61

Post by SV_BubbleTime »

tartoran wrote: post #47
MattGaiser wrote: post #18

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

Better than writing really long descriptive function names is to not get carried away but write well described function names that show some intent or description and are chosen carefully. I worked on some code bases using long descriptive function names (inherited from another dev) and it wasn’t always useful. It was overkill. The descriptions were either too generic, too descriptive (redundant in half the cases) or…

x100 on intent!

Even something simple like “if the function starts with “is” it will return a Boolean has helped me organize things that return status codes and have side effects. Small thing, but I like it.

Re: Writing Well-Documented Code – Learn from Examples

#62

Post by billytetrud »

I agree with others, code commentary shouldn't be a novel. Comments should only provide info that the code can't make easy to understand. Why it was done this way, what it's intended to do, complex or nonlinear interactions that aren't clear from the code. But adding things that make reading the code sound more like English isn't helpful, it's extra work and prone to getting out of sync.

Re: Writing Well-Documented Code – Learn from Examples

#63

Post by SV_BubbleTime »

willseth wrote: post #51

The Protobuf documentation made me cringe. Every character of its "personality" adds a cognitive burden for the reader and a maintenance burden for anyone who has to update it. If a developer wants to be cute with the same brevity and clarity that the comments would have otherwise, fine. Otherwise it's self-indulgent performative trash that should be rejected in review.

Absolutely. That was not a good example for me.

> self-indulgent performative trash

A little harsher than I would have used; but now that you say it.

>that should be rejected in review.

Without question. I would have absolutely denied that until it was trimmed to at most 10% of what was there.

Re: Writing Well-Documented Code – Learn from Examples

#65

Post by nicoburns »

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…

> 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

Isn't the answer to that obvious? The code is significantly constrained in form by having to be executable. The comments have no such restriction.

Re: Writing Well-Documented Code – Learn from Examples

#66

Post by codethief »

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…

While surely not the source of the saying, antirez argues in a similar direction:

> You may think that writing comments is a lesser noble form of work. After all you can code! However consider this: code is a set of statement and function calls, or whatever your programming paradigm is. Sometimes such statements do not make much sense, honestly, if the code is not good. Comments require always to have some design process ongoing, and to understand the code you are writing in a deeper sense. On top of that, in order to write good comments, you have to develop your writing skills. The same writing skills will assist you writing emails, documentation, design documents, blog posts, and commit messages.

In any case, you're making a good point, though I would argue that the reverse of the saying (with the modification that "expectations" get replaced with "trust") also holds:

If someone is not able to write intelligible, stringent English, I wouldn't trust them to write good code, either, because writing good code requires similar qualities (good stringent structure, empathizing with the future reader of your code etc.) and, as antirez argues convincingly, it also requires writing comments (which are in plain English).

Re: Writing Well-Documented Code – Learn from Examples

#67

Post by codethief »

ainzzorl wrote: post #30
codethief wrote: post #9

Earlier quoted context omitted.

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

> A lot of code files starts with lengthy copyright notices, and no one seems to mind.

Hmm, maybe I'm the odd one out but I actually find them quite annoying if they're longer than just a few lines.

In any case: People often just scroll past and ignore lengthy comments at the top (maybe precisely because they're used to copyright notices), so I think a short comment at the top like "For design considerations and reasons this code has been written the way it is, see the very bottom of this file" will attract much more attention.

> Also, I don't think I've ever seen comments at the bottom of a file!

True, but how often do you see code comments about design considerations in the first place?

Re: Writing Well-Documented Code – Learn from Examples

#68

Post by codethief »

kyleee wrote: post #23
komon wrote: post #12

Earlier quoted context omitted.

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.

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

#69

Post by seanwilson »

For the first example with conditions, I much prefer rolling the "why" of the comments into boolean variable names where possible e.g.

   // We still have burst budget for *all* tokens requests.
   if self.one_time_burst >= tokens {
      ...
   } else {
      // We still have burst budget for *some* of the tokens requests.
becomes something like (I'm missing context but you get the idea):

   enoughBudgetForAllTokenRequests = self.one_time_burst >= tokens

   if enoughBudgetForAllTokenRequests
      ...
   else
      ...
I don't see this often though. I see the commenting pattern a lot where the comment usually duplicates the "what" of the conditional code, and it's often ambiguous if the comment is talking about the condition or a whole branch.

I think a descriptive variable makes the code easier to skim, it's more precise and less likely to become inaccurate. For a big complex conditional, you can break in up into several well-named boolean variables you compose together (but obviously comment the bits that can't be covered by a concise variable name).

Re: Writing Well-Documented Code – Learn from Examples

#70

Post by namelosw »

There are too many comments in there.

Comments are not the first tool people should try to reach because:

1. That's a lazy way to make the code clear, most code should be self-descriptive. If the teams are spamming comments it's likely to be a bad code base already.

2. There's no guarantee the comment is compatible with the code: It's natural language and there's no obvious way to test that. After versions of modification, the comments might still look like they make sense but that's not how the code work anymore.

Two alternatives:

1. Declarative programming: Try to leverage declarative programming styles more. For example, top-down style dynamic programming or memoization is always more readable and less error-prone than the bottom-up ones. You don't have to fully adopt functional programming or logic programming, but do take some inspiration from them.

2. Testing. Tests are like comments, they reflect some meaning of the code. Tests are not like comments, if the code breaks, they break.

Of course, comments are very valuable, but it's most valuable when applies in the right spots only.

Post reply on HN