When I see code with a lot of inline comments, I can’t help but think that a lot of them would make sense to implement as trace log messages instead. If you’re going to write all these messages documenting the flow of the program, why not give yourself the ability to flip a switch and output them somewhere?
Writing Well-Documented Code – Learn from Examples
91–100 of 153 posts
Re: Writing Well-Documented Code – Learn from Examples
#92Personally 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
…and on the reviewer(s) who accepted the code change even though the comments no longer match the code.
Re: Writing Well-Documented Code – Learn from Examples
#93Earlier quoted context omitted.
Yes, there should pretty much always be this. You've just written some messy unclear code for performance reasons, so it deserves more thorough tests than average. And you've already written the clean version anyway, since you hopefully didn't write the optimized version until after you profiled the slow one. So it's not even significant extra work to turn that into your test suite.
This could also be a great way to check if your optimized version is still necessary with new versions of your language implementation. The more I think about it, the more it seems like a great idea.
I wouldn't generally throw benchmarking into the unit test process, because it can be brittle. What if something else clobbers the CPU on your test machine at just the wrong time.
What you really want from your unit tests is for them to run quickly, so you run them as often as possible, and reliably, so any failure means something is wrong. I'd use the slow implementation just for checking correctness.
But separately, if you want to add a performance benchmarking process (great!), you have a reference baseline implementation for free.
Re: Writing Well-Documented Code – Learn from Examples
#94Speaking of source code comments, antirez (of Redis fame) wrote a fantastic article[0] about that topic some time ago and I still recommend it to colleagues whenever they make the hollow statement that "code should and can be intelligible on its own, without any comments". [0]: https://web.archive.org/web/20210226004600/http://antirez.co... (I still don't understand why he deleted his blog)
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.
Very often it is just not possible to truly understand code without comments (or other form of documentation). This becomes obvious if you realize that code by itself can only tell you what is being done, but not why.
Re: Writing Well-Documented Code – Learn from Examples
#95For 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
#96some 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…
> understand why the code is there
You hit the nail on the head here. This is the single most important reason for having comments in code (aside from just being a part of a coding standard).
Re: Writing Well-Documented Code – Learn from Examples
#97Earlier quoted context omitted.
This could also be a great way to check if your optimized version is still necessary with new versions of your language implementation. The more I think about it, the more it seems like a great idea.
I wouldn't generally throw benchmarking into the unit test process, because it can be brittle. What if something else clobbers the CPU on your test machine at just the wrong time. What you really want from your unit tests is for them to run quickly, so you run them as often as possible, and reliably, so any failure means something is wrong. I'd use the slow implementation just for checking correctness. But separately…
Maybe not directly in the unit tests that you always run on your machine, but having them around could be a good idea.
Re: Writing Well-Documented Code – Learn from Examples
#98I had a lot of trouble reading that code. I kept getting distracted by the comments and missed the code. The code seems pretty self-explanatory. I have some changes I would make, but they really depend on performance vs depth (modulo the burst vs budget bug).
// Hit the bucket bottom, let's auto-replenish and try again.
self.auto_replenish();
All of the comments in reduce are redundant, this is what I would write at the top, so that anyone using the method doesn't have to page through to figure out what it does, it also makes the "smells" more obvious:
// reduce: attempt to consume tokens from bucket,
// starting with one_time_burst, overflowing to
// budget.
// (keep comment only if _expensive_):Performs
// auto-replenish when
// burst is emptied, and budget has insufficient
// tokens.
// Asserts size, but only on replenishment.
// On OverConsumption, entire bucket is emptied.
// On Failure, only one_time_burst is emptied.
// In all cases, tokens is reduced by amount
// fulfilled.
I'm also curious why burst is consumed, then budget. I would expect _budget_ to be consumed first (with refill) with overflow into burst? My expectation is for burst and budget to have different refill schedules in auto_replenish, so using burst first would result in more failures by missing refill opportunities.
I'm also curious why the size assertion is only on requests that result in refills. Is it guaranteed that size = max(one_time_burst + budget)? Why care about the difference? Is hogging the tokens "bad"?
Then, I'd work to remove the need for those comments - particularly the need to explain what happens on error - which should be "nothing", or that the bucket is emptied of whatever is available, not something in between.
Finally I'd remove the mutation of tokens, returning either unfulfilled or fulfilled in the return value.
Re: Writing Well-Documented Code – Learn from Examples
#99Personally 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?
Re: Writing Well-Documented Code – Learn from Examples
#100Personally 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
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