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.
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.
Better yet, turn magic numbers into constant variables whose name becomes the comment. Of course, comments can also provide additional context :)
const ONE_HOUR_IN_MS = 3600000
Instead I would like to see const RESEND_DELAY = 3600000 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. const RESEND_DELAY_MS = 1 * 60 * 60 * 1000; // one hour
Essentially the same, but the lack of extra variable spares one jump. Also you can change it without introducing a new variable (no dependency). const ONE_HOUR_IN_MS = 3600000
const RESEND_DELAY = ONE_HOUR_IN_MSconst RESEND_DELAY_MS = 3600000; // because TTL in Agora
const RESEND_DELAY_MS = 3600*1000; // because TTL in Agora
Easier to check for the right number of zeros
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.
Also, 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!
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.
This should be easy enough to verify during code review, no?
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!
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.
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.
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.
What actually would happen is the next person comes along and changes the code and doesn’t update the external doc because it’s probably buried among 100 other pages on confluence and they don’t even know it exists
If the comment is in the code they will see it and update accordingly
The external doc is an explanation of what the value does, and what happens when that value is updated, not why it's set to a specific value.
I’ve put this into practice numerous times with positive effect, so my more relevant experience tells me this is a winning strategy, compared to in line docs, which are objectively worse in nearly every way.
But your more relevant experience tells you that’s wrong. I really don’t understand such aversion to a one or two line comment, but let’s just not work together in the future. ;)
You’ll be fairly lonely if you reject working with everyone who’s read Clean Code, and truly alone if you won’t work with anyone who understands something better than you.
And I think people who read Clean Code and aren’t dogmatic and condescending about trivial choices like this are pretty fine.
And I'm not dictating anything, or being dogmatic and condescending, but I guess it's easier to think I am if you're trying to have an Internet Argument Moment.
You literally dictated that explanatory code docs shouldn’t talk about rationale for constants. And your evidence for this is that apparently Clean Code says so.
> condescending
Well you can claim not to be condescending all you want but that’s how I interpreted your explanation that the only reason I disagree is that you “understand it better,” and I’d imagine that’s how most people would read it.
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.