14 ms·
Writing Well-Documented Code – Learn from Examples
- mibollma 5y agoI like the idea of codecatalog. Would be nice to see some functional Kotlin examples that go beyond list processing.
- ainzzorl 5y agoThanks! If you know some good examples, please consider proposing them: https://github.com/ainzzorl/goodcode/issues/new?assignees=&labels=new+example&template=new-example-proposal.md&title=%5BNEW+EXAMPLE%5D+PROJECT+-+TITLE https://github.com/ainzzorl/goodcode/issues/new?assignees=&l...
- Fire-Dragon-DoL 5y agoThe first has an enormous amount of visual noise and it's definitely over commented. 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
- nerdponx 5y agoThe "first things first" comment was bad, but I'd rather have it + the other comments than have none of them.
- codethief 5y ago> 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 verbosity. EDIT: Confused first and second example
- ainzzorl 5y agoA 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 originally written though.
- codethief 5y ago> 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?
- ainzzorl 5y agoI 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 https://news.ycombinator.com/item?id=28416777
- Lio 5y agoIt’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 can’t be trusted.
- Rapzid 5y ago> 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.
- achenatx 5y agosome 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 limiting when they are zero. This one is great, though at first glance I cant relate the actual code to the comment, at least I understand why the code is there. // We still have burst budget for *some* of the tokens requests. // The tokens left unfulfilled will be consumed from current `self.budget`. tokens -= self.one_time_burst; self.one_time_burst = 0;
- komon 5y agoIn 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.
- kyleee 5y agoGood 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.
- codethief 5y agoI agree, though I think it would be even better if variables were named "token bucket capacity" and "refill time" in the first place.
- bcyn 5y agoIt’s hard to judge out of context. IMO None meaning “disable limiting” should be a docstring/comment at the method level, describing what its return values mean, not inline next to this code.
- codethief 5y agoSpeaking 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.com/news/124 https://web.archive.org/web/20210226004600/http://antirez.co... (I still don't understand why he deleted his blog)
- cpach 5y agoHuh? That URL is still alive: http://antirez.com/news/124 http://antirez.com/news/124
- codethief 5y agoHuh? I've been getting > Sorry, I can't find that page :-/ for several months
- ReactiveJelly 5y agoWorks with pure HTTP. Try it in curl? Also see my sister comment for elaboration
- ReactiveJelly 5y agoMaybe it's a buggy HTTPS redirect in GP's browser? Due to HSTS or something? The HTTP version of your URL works fine. The HTTPS version has an expired cert. If I click past that, it redirects to redis.io, then gives a 404. I know antirez is a smart guy, but if this is some kind of "I'm taking a bold stance against HTTPS" then I'd rather read the archive.org link with functioning HTTPS. My threat model prefers trusting archive.org to correctly reproduce the blog, over trusting everyone between me and antirez.com.
- kyleee 5y agoLet's hear more about your threat model that causes you to wory about nefarious content being injected into a blog post about comments in code
- invincivlepvt 5y ago<a href="https://www.instagram.com/invincivlepvt/">Logo https://www.instagram.com/invincivlepvt/">Logo Designing Jalandhar</a>
- invincivlepvt 5y agohttp://www.uniquethings.in/ http://www.uniquethings.in/
- Sykander 5y agoA lot of this I find to be kinda bad commenting, you've got to remember NOT to just directly comment on what the code is doing, but rather explaining why. With future updates your comments will eventually be wrong if they do anything other than give context. If all your comment does is say what the code on the next line is doing, don't. Instead just try to make the next line more readable.
- didip 5y agoI have a simple rule to go by. Comments should describe “why” and the code should describe “what”.
- ozim 5y agoI agree and first example in the article is all comments describing what the code is doing. There is not a single one explaining why. Well I stopped reading further.
- ainzzorl 5y agoWhile 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.
- Rapzid 5y agoAgree; 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.
- SV_BubbleTime 5y agoWHY comments drastically improved my code. I’ve similarly been paying much more attention to convey INTENT which I think is massively missing from computer science. The code might suck, but if the intent is clearly defined, it helps to refactor later.
- ChrisMarshallNY 5y agoAgreed. That's what works for me.
- dadlangia4 5y agoWay to much
- MattGaiser 5y agoI 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.
- SavantIdiot 5y agoI worked with a guy who wrote a CPU simulator and exceeded the MSVC 256-char function name limit. It's hard when you like 80/100 col code and a function name is longer than that.
- rightbyte 5y agoDoes escape new line work in function names in C? Brb. Edit: Hah. It does.
- tartoran 5y agoBetter 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 handling such long saussage names was simply tiring. When you have to scroll right to read a name it becomes a problem.. The takeway is that merely writing very long descriptive names isn’t a silver bullet and could cause harm despite good intentions. I suggest going back a after a few days for a refactoring (renaming functions or variables) and see how it reads to you. Then repeat the process a few days later when you’re even more detached from that code. In many cases self documenting code is going to help you remember the model you had in your head when building it. And if done well it will help others as well, your code will end up not giving headaches to future maintainers.
- SV_BubbleTime 5y ago
- crateless 5y agoI wish there was an option for dark mode or something.
- deleted 5y ago[deleted]
- ChrisMarshallNY 5y agoI find that doing a "headerdoc" kind of thing works for me. I did write up a thing about it, but it's a long read, so folks don't usually read it: https://littlegreenviper.com/miscellany/leaving-a-legacy/ https://littlegreenviper.com/miscellany/leaving-a-legacy/ Has some pretty heavy-duty examples.
- jpswade 5y agoThe code should explain what it's doing (self documenting code) and tests should explain why it's doing it. Comments tend to just become a place for misinformation or get disconnected from the actual logic. Adding more comments sometimes doesn't clarify the situation, it just acts as a second source of truth.
- KronisLV 5y ago> The code should explain what it's doing (self documenting code) and tests should explain why it's doing it. I agree at a surface level, however: - this makes us assume that there are tests in the first place - this makes us assume that someone will read these tests instead of asking the developer - this makes us assume that these tests will be readable enough on their own to replace free form text - this makes us assume that these tests will even be able to contain a representation of why the code exists - personally, i have never seen a test that explains a business requirement with enough context not to miss out on details - i have also never seen code that encapsulates these requirements 1:1, without getting too mixed up in implementation details I think that code definitely should describe what it's doing, tests should explain how it's doing it as far as possible (though this requires discipline to have loosely coupled and testable code, which isn't always the case) and that there still should be comments that explain the realities of needing technical solutions for people problems and all of the aspects that are carried with this. Doing anything less feels like giving ourselves constraints that will lead to suboptimal results because the tooling and testing solutions aren't quite there yet. Maybe when frameworks and languages will become more expressive, we'll be able to live without comments. However, that day may not come anytime soon. Nor will companies be interested in the overhead that writing extensive and good tests entail, nor will they want to wait for their engineers to figure out how to convey everything in computer code, as opposed to just dropping some comments into the codebase, right next to the actual code that they concern. Maybe when companies are ready for 50% of the development time to be spent on testing software, that won't be an issue. That day may also not come anytime soon. As a possible counterpoint, look at RSpec, i think it's headed in the right direction: https://rspec.info/ https://rspec.info/
- Zababa 5y ago> and tests should explain why it's doing it I was going to say "So for performance "hacks" there should be a clean implementation that's benchmark against the current implementation for example?" as a way to disprove what you said, but while writing it I realized that it may actually be a pretty good idea.
- pcmoney 5y agoPersonally 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 comment. I generally open git blame to see if the comments predate any code now. Tests on the other hand almost never lie. Readmes or comments explaining why something exists vs what it allegedly does are generally much better. If you can’t write expressive code why would you assume your English is much better?
- tempest_ 5y agoThat is how I feel about these comments. In a vacuum I like them and when I bump into a piece of 10 year old code commented like this it is great. There is one caveat however, they have to be meticulously maintained and always updated to reflect every change made to the code. It is a huge caveat because more often than not the comments are out dated and no longer reflect the actual code and at that point they are detrimental.
- coliveira 5y agoThat's why Knuth had the idea of creating literate programs where documentation and code was maintained in a single block. Unfortunately, this idea was never used in large scale.
- kevin_thibedeau 5y agoHave you ever tried to read the soup he created with code blocks rearranged to suit the generated text rather than any future maintenance coder?
- RobertKerans 5y agoYeah, I think there's a fundamental problem with the implementation -- with small, single-file programs where the code can be written in a chronologically linear manner it works well. But with that there's no need for reordering logic, so much of the more complex parts of weaving are redundant. Scripts, for example, are pretty easy to set up as [for example] markdown files, which works great (particularly in a project that requires a set of helper scripts which need why communicated -- having a set of markdown files in a folder makes it IME much more ergonomic for other devs). Anything larger and it gets increasingly fiddly and (again IME) not worth it.
- 29athrowaway 5y agoWell documented code is respectful of the maintainer's time. Nobody wants to read a monologue full of noise to understand what is happening. Comments are not monologues. Explain what the line you are commenting does, and perhaps elaborate why. But always acknoweledge: more words = more patience required = more maintenance cost. Also, nobody will care about what your name is in 2 years. Do not make the code about you.
- Zababa 5y agoOn the other hand, if something is missing in the comments, it could take days to find out exactly what you need. Maybe a "level of comments" like log levels could help here?
- ahallock 5y agoI like meta comments about the business or technical decisions behind the code. You can come up with clever method and variable names to help enlighten the reader, but nothing beats an intimate, first-hand account explaining the why.
- willseth 5y agoThe 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.
- SV_BubbleTime 5y agoAbsolutely. 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.
- lifeisstillgood 5y agoTime and active readers. Want well documented (and tested and thought out) code? Then give the coders people outside of their team / hierarchy who are going to check it / read it / use it. And then give them time. And repeat.
- rgoulter 5y agoWorth comparing: http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html 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.. I think the needs and expectations for documentation are different than if the project or team is large and change is slow.
- codethief 5y ago> 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).
- billytetrud 5y agoI 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.
- seanwilson 5y agoFor 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).
- samsquire 5y agoLong 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 5y ago[deleted]
- deleted 5y ago[deleted]
- deleted 5y ago[deleted]
- SquishyPanda23 5y agoenough_budget for what though? That's not a very clear variable name.
- gnubison 5y ago
- namelosw 5y agoThere 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.
- pojzon 5y agoIMHO writing a well-documented code requires a discipline and a set of good habbits. One of those habbits is to update documentation (tests/comments) when software is evolving. Unfortunately it is a very rare habbit it seems.
- SergeAx 5y agoOn my team fit/engineering values interview I always asking about benefits of autotests. People who said that tests written alongside the code are the best documentation are getting a mental "plus one point".
- jmartrican 5y agoI have seen two extremes on this over the years... comment a lot, or do not comment at all. In the teams I work in, I would love to see a more moderate and practical view on the matter. I get the whole document with your code, and practice that. But sometimes we end up with variable names that get very long and start leading not the most aesthetic code that gets formatted in a very vertical way. Don't know the right answer, but suspect the two extreme views are not correct.
- blitz_skull 5y agoIf you must dump a 5-paragraph essay about why something exists, you put it in the git commit message so when you git blame those lines, you see the history of the code. These examples are a fucking nightmare.
- bandyaboot 5y agoWhen 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?
- jpollock 5y agoI 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(); Is ugly. Why repeat in English exactly what the code says? I don't even know what language this is, but I know it's replenishing the tokens in the bucket. 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 don't understand why OverConsumption is different to Failure. Both will result in throttling by the caller. The reason for the difference should be documented. 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.
- jpollock 5y agoIf we change the code, getting rid of if statements, it's easier to see what happens by removing if's. I've changed BucketReduction to be a pair, and fixed the strange behavior on error. Swapping "fromBurst" and "auto_replenish" would reduce the number of throttling events. This solution does have more branches than the original, hence readability vs performance. It's still not exception safe, auto_replenish could throw and leave the state undefined. BucketReduction reduce(long tokens) { long fromBurst = min(tokens, burst); burst -= fromBurst; tokens -= fromBurst; if (tokens > budget) { auto_replenish(); } long fromBudget = min(tokens, budget); budget -= fromBudget; tokens -= fromBudget; long totalConsumed = fromBurst + fromBudget; if (tokens == 0) { return new BucketReduction(Success, totalConsumed); } if (totalConsumed + tokens > size) { return new BucketReduction(OverConsumption, totalConsumed); } return new BucketReduction(Failure, totalConsumed); }
- timdaub 5y agoIMO, comments are needed when the code itself can't express something necessary to understand its overall function. I've found that hence e.g. for rather complex statements where the code isn't lacking information, not commenting is the correct approach. Whereas sometimes, when I'm forced to write exceptional code because of e.g. a workaround, a comment can nicely introduce my future self and other readers to the context.
- vinaygaba 5y agoI have a really similar motivation behind a project that aims to teach Jetpack Compose in the same fashion and funny enough, the name is also pretty similar to the title of this thread - Learn Jetpack Compose By Example. You can find it here - https://github.com/vinaygaba/Learn-Jetpack-Compose-By-Example https://github.com/vinaygaba/Learn-Jetpack-Compose-By-Exampl... There's a ton of comments in every example (even though they might be redundant across the examples) and the idea is that you should be able to learn this new framework by merely reading through the examples.
- makeitdouble 5y agoMore 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 they?), as anyone could go read the wikipedia article instead. Comments living with the code have their benefits, but here I can’t imagine these huge comment blocks or algorithm related warnings get revised anytime outside of project wide refactoring. What we also miss by having these comments inlined is the higher perspective of how it works with the other classes or how it fits in their running context. Anything that spans multiple class and/or methods makes it difficult to decide where to put the info and what scope it should have. People usually end up explaining the same things at 3 or 4 places in sublty different ways, which makes no one happy. An exemple of that, this struct description > /// TokenBucket provides a lower level interface to rate limiting with a /// configurable capacity, refill-rate and initial burst. This comment is hinting at a sequence where ‘TokenBucket’ needs to be a configurable lower level interface. But what is that sequence, what needs it to be lower level, is there higher level interfaces ? I’ll sure end up spelunking the rest of the doc to get answers to that.
- pcmoney 5y agoExactly, 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.
- nyberg 5y agoBut the new class(es) needs to be documented regardless as the relation to the code has changed from the old. Keeping documentation in another document would see this going out of sync over time until the document doesn't at all reflect how the code looks. Not updating anything at all will leave others clueless of why the change was needed 4 months later and might see the other classes grow to the same size. Thus, eventually the code base will once again be opaque unless you ask the nearest person that worked on it last. A nicer way of handling the flow of the document would be to use a literate programming tool that allows for keeping code snippets in an order which makes sense for the documentation rather than sprinkling as comments between the code. That way, code review happens at the same time as documentation review with code being local to the text documenting it in a format which is easy to understand for both.
- deleted 5y ago[deleted]
- dan-robertson 5y agoI was not very impressed by the token bucket example. Firstly, it is totally ridiculous to need to write your own implementation of gcd and the comment is silly and unnecessary. Secondly, the implementation for the token bucket seems to just be bad. A simpler implementation is as follows: - Input number of tokens and refill time. - Output the constant state describing the limiter: the max number of tokens and the time to get a single token (= refill time / size, ignoring rounding issues which shouldn’t generally matter if your times are in nanos) - The only mutable state is a single time instant: the time when the limiter becomes full - to attempt to take a token, compute max(0,full_time - now) / new_token_time and if this is less than or equal to the size of the bucket minus the number of tokens you want, you may withdraw and set full_time := max(full_time, now) + tokens_to_withdraw * new_token_time If that division is concerning then you should either attempt to withdraw from the rate limiter less frequently or you should not be using one at all. The rest of the code is about scheduling events to happen when there are free tokens in the ratelimiter. This is a different problem and also over-complicated. You should either poll and retry periodically with your most important event (rather than whatever event you thought was most important when the bucket became empty) though you then want to be careful about stale tasks never running, or you should just have a queue of pairs (Task, cost) where cost is an int. after withdrawing tokens from the ratelimiter or when the queue transitions from empty to non-empty, peek the top item and set a timer for rl.full_time - rl.new_token_time * (rl.size - cost) and when the timer fires (or immediately if the time was in the past) you can dequeue, withdraw cost tokens, and run that top task (then repeat.)
- jti107 5y agoi've found that well written code + useful comments + comment with link to design document works pretty well. i got an email about code i'd written 10 years ago...thanking me for taking the time to document everything.
- throwaway984393 5y agoDon't sleep on /usr/share/doc/, /usr/share/info/, and /usr/share/man/ either. Code comments are not a replacement for real documentation that is written from the perspective of either a user or a developer. If you can somehow auto-generate meaningful documentation, that's great, but often whatever is auto-generated is only good in theory.
- rufus_foreman 5y agoI went from my last job where every method and variable declaration had to be commented to my current job where there isn't a specific rule against comments in code but if you put in a PR with comments in it, you're going to get rejected after being laughed at. I thought I would miss it, but I don't miss the documentation. Code doesn't lie.
- vaylian 5y agoBut code doesn't always explain why it is the way it is.
- rufus_foreman 5y agoIt does a hell of a lot better job than comments. I can't believe you've got me justifying this policy. But it does seem to work. shrugs
- 15rthughes 5y agoYou really can’t believe someone wants you to justify a stupid rule and toxic workplace environment?
- lloydatkinson 5y agoSounds like a toxic environment.
- icholy 5y agoYou're an idiot.
- alecbz 5y agoComments like x = 4 # Sets x to 4 Are of course silly and I'd laugh at them too, but comments when used correctly are hugely valuable. Even a stale comment can be helpful in giving you a sense of what people were trying to do. Do you not use commit messages either? Do you have any documentation at all?
- penguin_booze 5y agoThe view I've developed on docuemntation over time is that it should be addressed outside in. What I look for--and also create, where possible--is a high-level architecture diagram that depicts all major components of the system. Then comes some description of typical control flow through the system, either visually or via. textual description. For example, "the request hits the server, then it goes here, does that etc.). What would be even better is to create a model of the system using something externally altogether, like TLA+. It need not be perfect right at the beginning, but over time, invariants can be put in place, and even possibly mechanically tested by a model checker. Just even the Next state disjunct would work great - it'll give me the superset of actions the system is capable of. To me, well-commented functions are all well and good; but without a high level understanding of how everything fits and works together, I doubt it'd be very helpful. It's like winning the battle but losing the war. I'm not a fan of relying on IDE-centric features either. What if my IDE is not yours?!
- Dowwie 5y agoCode Catalog has such great potential. I really hope to see it succeed. Thanks to all of the contributors who are making it possible.