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

121–130 of 153 posts

Re: Writing Well-Documented Code – Learn from Examples

#121

Post by cratermoon »

unchar1 wrote: post #76
cratermoon wrote: post #50

Earlier quoted context omitted.

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

I'm a big fan of Henney and have watched a lot of videos of his talks, so that's probably it.

Re: Writing Well-Documented Code – Learn from Examples

#122

Post by AlexCoventry »

pcmoney wrote: post #116
AlexCoventry wrote: post #99

Earlier quoted context omitted.

> If you can’t write expressive code why would you assume your English is much better? Because English is optimized for communicating human intent?

I guess aside from assembly and very low level or highly specified languages aren’t programming languages as well?

In my experience, it's much easier to get just the right level of abstraction for quick reader comprehension in natural English, compared to any programming language.

Re: Writing Well-Documented Code – Learn from Examples

#123

Post by prpl »

tln wrote: post #113
prpl wrote: post #100

Earlier quoted context omitted.

There’s not many code review platforms that are great at showing you relevant comments in a diff because they are often in a much different part of the file, so I kind of think it’s hopeless in a large code base to catch this sort of thing in a code review

I now use VS code for reviewing PRs and it's easy to spot and then touch up comments. With GitHub, not so much. Not sure why code base size would make it harder... Workflow? Code unit size? The larger the code base, the more comment discipline matters IMO

I was mostly thinking about how small changes can sometimes touch a larger quantity of files on moderate or large code bases, so a bit more things to wade through when doing a review, but point taken.

Re: Writing Well-Documented Code – Learn from Examples

#124

Post by cratermoon »

einpoklum wrote: post #82
cratermoon wrote: post #50

Earlier quoted context omitted.

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 (or whatever language)? The comments don't say the same thing as the code. In the comments, the author might tell us - albeit not clearly or in proper English, what they want to achieve, or why they're doing it this way.

If someone takes a dozen lines of convoluted code to express what can be done in 2-3 lines concisely, the explanation isn't going to help. Think of the worst mess of if/then/else clauses you've seen, or someone who switches on a type instead of using polymorphism. Even if they can explain it well enough that you can follow it, the comments aren't going to improve the understanding much. They are more likely to add cognitive load and make it harder to grasp the intent.

Re: Writing Well-Documented Code – Learn from Examples

#125

Post by TheoLib »

pcmoney wrote: post #117
prpl wrote: post #100

Earlier quoted context omitted.

There’s not many code review platforms that are great at showing you relevant comments in a diff because they are often in a much different part of the file, so I kind of think it’s hopeless in a large code base to catch this sort of thing in a code review

Comments are not inherently bad but they do have inherent short comings. Still a useful tool but one that should be reached for rarely and last.

Comments are "reached for rarely and last". Whatever shortcomings comments have pale in comparison to being faced with and trying to figure out undocumented or too sparsely commented code, which, in my long experience, has been an order of magnitude more prevalent than sufficiently documented/readable code. Heck, even a wrong comment is sometimes preferable to no comment if it at least gives me a clue as to what the purpose of that section of code was at some point in its evolution.

Re: Writing Well-Documented Code – Learn from Examples

#127

Post by flavius29663 »

seanwilson wrote: post #69

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

This. And the extra documentation is provided by tests, which are living code and evolve together with the production code. That should be enough to understand the code.

The top of the file comment is good and well received. At the same time, you could have a wiki page with that info, where you can also have diagrams etc.

Re: Writing Well-Documented Code – Learn from Examples

#128

Post by prpl »

TheoLib wrote: post #125
pcmoney wrote: post #117

Earlier quoted context omitted.

Comments are not inherently bad but they do have inherent short comings. Still a useful tool but one that should be reached for rarely and last.

Comments are "reached for rarely and last". Whatever shortcomings comments have pale in comparison to being faced with and trying to figure out undocumented or too sparsely commented code, which, in my long experience, has been an order of magnitude more prevalent than sufficiently documented/readable code. Heck, even a wrong comment is sometimes preferable to no comment if it at least gives me a clue as to what the…

I personally strive for code that can be read as a sentence, especially in complicated sections of code.

This sometimes leads to weird intermediate variables which might look superfluous, e.g. intermediates like:

foo_has_at_least_1 = len(foo) >= 1

(not a great example, usually it’s a bit more semantics. than that) but later code using those intermediates reads as english, which can reduce cognitive load when reading the code and obviate comments, and preconditions are more readily verified.

It’s literate programming and I prefer that to long comment blocks like those in some of the examples. All that said, it can be hard to get coworkers into such a habit, especially those who feel brevity and abbreviation is a virtue.

Re: Writing Well-Documented Code – Learn from Examples

#129

Post by x-shadowban »

SiVal wrote: post #120
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 problem with all discussions of good commenting style is that it's like debating good footware. Good for what? Office? Hiking in snow? Walking on the beach? Except that we have different footware for different uses but only one set of comments. Having such a limited commenting syntax is like assuming one permanent type of footware and debating which one would be best. I'd much rather have a smarter commenting sys…

Inline graphviz annotations would be very nice. Store the text, IDE "codelens" renders it out

Re: Writing Well-Documented Code – Learn from Examples

#130

Post by SquishyPanda23 »

gnubison wrote: post #115
SquishyPanda23 wrote: post #111

Earlier quoted context omitted.

enough_budget for what though? That's not a very clear variable name.

IMO that should be in a comment, instead of duplicating that information every time you mention the variable. (This applies more for local variables in short blocks than for, say, global variables.) At some point the length of the name makes everything around it harder to read, since it’s been pushed so far apart.

As a general rule I completely agree.

On the other hand, token bucket implementations are hard to understand and hard to debug. And an ambiguous variable name can cause trouble because some devs might think it "obviously" refers to enough budget for some other slice of requests.

I think my preferred solution here is to extract the condition into a boolean function with a long name like HasBudgetForAllRequests. This solves the long variable name issue and also gives you a useful place to add to your budget computation logic if you need to.

Post reply on HN