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

111–120 of 153 posts

Re: Writing Well-Documented Code – Learn from Examples

#111

Post by SquishyPanda23 »

samsquire wrote: post #90
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_…

Long variable names mean you perceive your simple code as being too complicated. It's an if statement. I would refactor your long variable name to something more compact like enough_budget.

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

Re: Writing Well-Documented Code – Learn from Examples

#112

Post by [deleted] »

samsquire wrote: post #90
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_…

Long variable names mean you perceive your simple code as being too complicated. It's an if statement. I would refactor your long variable name to something more compact like enough_budget.

[deleted]

Re: Writing Well-Documented Code – Learn from Examples

#113

Post by tln »

prpl wrote: post #100
nijave wrote: post #77

Earlier quoted context omitted.

>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

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

Re: Writing Well-Documented Code – Learn from Examples

#114

Post by Gh0stRAT »

oxfeed65261 wrote: post #92
nijave wrote: post #77

Earlier quoted context omitted.

>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

…and on the reviewer(s) who accepted the code change even though the comments no longer match the code.

I agree, but git and most code reviewing tools I've used only show a few lines of surrounding context so the reviewers might not even realize there's a comment further up that needs updating.

Re: Writing Well-Documented Code – Learn from Examples

#115

Post by gnubison »

SquishyPanda23 wrote: post #111
samsquire wrote: post #90

Earlier quoted context omitted.

Long variable names mean you perceive your simple code as being too complicated. It's an if statement. I would refactor your long variable name to something more compact like enough_budget.

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.

Re: Writing Well-Documented Code – Learn from Examples

#116

Post by pcmoney »

AlexCoventry wrote: post #99
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…

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

Re: Writing Well-Documented Code – Learn from Examples

#117

Post by pcmoney »

prpl wrote: post #100
nijave wrote: post #77

Earlier quoted context omitted.

>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

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.

Re: Writing Well-Documented Code – Learn from Examples

#118

Post by axiosgunnar »

omegalulw wrote: post #104
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…

Yup, the rate limiter comments are unhelpful. A top level comment explaining the idea is fine (and very useful) but code should largely be self documenting.

Which it often is, but they still wrote a comment, leading to ridiculous stuff along the lines of

> // Returns None is x = 0

if x = 0 { return None }

Re: Writing Well-Documented Code – Learn from Examples

#119

Post by pcmoney »

makeitdouble wrote: post #105

More and more I feel these huge comment blocks with the following inline comments sprinkled everywhere should really be a separate documentation file with its own structure where anyone not familiar enough can get up to speed, and understand the core principles behind the code written here. For instance in the firecracker example, they don’t write 3 pages of block comments to explain the token bucket algorithm (or do…

Exactly, I dont want to have to go in and refactor a bloated class into 4 classes and then have to go refactor the short story they wrote about it.

Re: Writing Well-Documented Code – Learn from Examples

#120

Post by SiVal »

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

I'm not talking about supplementary docs stashed elsewhere to gather dust. I'd like to have expandable comments right where they are needed but usable differently for a glance at familiar code or puzzling through unfamiliar code. Something very brief that doesn't clutter the code, a couple of words or no words at all, with an expansion arrow to something more detailed, expanding to something fully documented with links to everything.

And comments with scope (this comment applies to this line, this one to the function, this to a group of functions...) that actively use the scope. By active I mean that if you make any edits to code in the scope of a comment, that comment changes color or some other mechanism similar to a Git merge conflict: You changed the code without changing the comment, so check and make sure the comment says what you want and click OK. You don't have to fix the comments immediately for each edit. Make a few changes, test, make sure it's working, but when it is, you can see at a glance which comments need to be checked.

The general idea is instead of debating The Best Way to Comment, consider ways to improve the commenting system itself.

Post reply on HN