5 ms·
Please comment your code, when it is is necessary. I don't need "we need to loop here from 1 to 50", I need "we have to rate-limit this function to under 60 tr
by EMM_386 5y ago
Please comment your code, when it is is necessary.
I don't need "we need to loop here from 1 to 50", I need "we have to rate-limit this function to under 60 transactions per second due to hardware requirements", etc.
If you are putting "magic numbers" anywhere, COMMENT it as to what that number is, why you chose it, etc.
I'm 30 years into this game and I still come across code that takes way too long to reason about.
- bkuehl 5y agoAgree completely. Also, good commenting skills take years to master.
- jgauth 5y ago> good commenting skills take years to master As a newer developer, it’s nice to hear you say that. I often find that I spend more time deliberating over comment wording and variable names than I spend writing the code itself!
- bkuehl 5y agoYou are on the right path! Most new devs don't even comment at all (and plenty of senior devs). As for variables names, I wouldn't fret about that. Yes, 'foo' isn't a good var name but the exact name doesn't matter as much as one would think.
- dwaltrip 5y ago> If you are putting "magic numbers" anywhere, COMMENT it as to what that number is, why you chose it, etc. Better yet, turn magic numbers into constant variables whose name becomes the comment. Of course, comments can also provide additional context :)
- srigi 5y agoAgree. I also add to this - name your constants by meaning, not value. Too many times I see const ONE_HOUR_IN_MS = 3600000 Instead I would like to see const RESEND_DELAY = 3600000
- wonderbore 5y agoBetter yet: const ONE_HOUR_IN_MS = 3600000 const RESEND_DELAY = ONE_HOUR_IN_MS
- mongol 5y agoI don't get why this is better. My approach: const RESEND_DELAY_MS = 3600000; // because TTL in Agora
- schobi 5y agoI would even go for const RESEND_DELAY_MS = 3600*1000; // because TTL in Agora Easier to check for the right number of zeros
- mongol 5y agoYes full agree
- sigg3 5y agoI've used stuff like this to do: const ONE_HOUR = 3600000; const RESEND_DELAY_MS = 2.5 * ONE_HOUR; // because TTL in Agora IMO it makes it easier for successor to fiddle with.
- tisc 5y agoI like to combine those: const RESEND_DELAY_MS = ONE_HOUR_IN_MS; Having the unit in the name saved me more than once and having non-contextual constants for sizes increases readability imo.
- 5y ago
- spike021 5y ago100% agreed. A trend I've noticed the past couple years is that people make the excuse of "code should be self-documenting" so they don't need to add comments. But then very helpful contextual hints that are not otherwise documented anywhere, like the one you provided, are completely non-existent and the original dev has left the team, it's been 2-3 or more years since the last time someone touched it, etc. Code should be self-documenting, don't get me wrong. But that's more in the vein of showing (what), not telling (why/how). There still needs some be some method of telling.
- chrismarlow9 5y agoNot disagreeing because I think comments can help solve confusion immediately in clever code. But when I tell people the code should be self documenting it implies there will also be: some form of git history to go along with it some single page architecture type of doc. No technical info, just like a README saying what this thing does and some 101, maybe a diagram. The "doc as part of the code" for me is really just a easy way to generate a "reference" for function signatures and specific code interfacing. And if you start off that way the reference is at least always up to date, because it's caught in review (ideally). As for updating the README that's just on the dev team to remember. I will say my opinion changes a bit with huge polyglot mono repositories. In those cases you need great docs and organization.
- satran 5y agoAs a general guide I comment the why, now the what. The what can be generally understood by reading the code. But the why is not so easy.
- twblalock 5y agoDon't do it unless you are going to treat keeping comments up to date the same way you treat keeping the code up to date. I've lost count of the number of times I've seen comments that were just wrong -- they applied to the code as it was written years ago, not today. Write good code, and it should be obvious how it works. Use comments sparingly and only when things are not obvious. Update the comments when you change the code, and make sure your code review process doesn't let outdated comments slip by. If you can't commit to the above policies, then don't comment your code at all.
- enraged_camel 5y ago>> Don't do it unless you are going to treat keeping comments up to date the same way you treat keeping the code up to date. This should be easy enough to verify during code review, no?
- isbvhodnvemrwvn 5y agoOnly if the comment is very local, and not e.g. two calls up the stack.
- pkolaczk 5y agoCode comments that are wrong can be very useful. I've found many bugs that way. If I find a comment that states an assumption that does not hold in the code, that's the first place I analyze when looking for a bug. And very often it turns out the comment was right, but the code was wrong.
- TameAntelope 5y agoYou can just name the variable to explain what the number is, and if you need more info, there should be a "Why?" doc somewhere explaining the context generally, WITHOUT tying itself directly to the current choice (otherwise you'll have to update the "Why?" doc every time you update the number in the code, which is almost certain to go out of sync). No need to interweave documentation and code, in most cases. Sometimes, when we fail to write good code, sure. But let's try to write good code!
- jonahx 5y ago>No need to interweave documentation and code, in most cases. Locality is the reason, and it's a good reason. Of course, I don't want to see paragraphs of explanation inline, but a one-line comment giving context for some choice that might be confusing is much better and faster to work with than a separate WHY doc.
- TameAntelope 5y agoIt's neither faster nor better, in practice. It's not faster because you can just name the variable whatever it is the value represents, so by adding a second descriptor (the comment) you're introducing needless complexity. It's not better because you really shouldn't be changing a value you don't understand the context around, which means reading much more than a one-line comment.
- hamburglar 5y agoI think the GP is referring to the very common case where you can’t possibly say what needs to be said in a single variable name, but one or two lines of comments is sufficient.
- jonahx 5y agoI am saying things like this: https://github.com/golang/go/blob/master/src/cmd/cgo/ast.go#L47 https://github.com/golang/go/blob/master/src/cmd/cgo/ast.go#... belong in the source code, not a Why doc. No variable naming can give that context.
- emrah 5y agoAgreed, despite the elephant in the room that when the company is in growth stage, comments rot, documentation rots, things change rather quickly and everything including comments become a liability. I'm not saying they shouldn't be written but they also need maintaining