That sounds wonderful in theory but it doesn’t seem realistic in general to have this doc explaining a particular constant and why/how it was chosen that doesn’t need updating if someone comes along and chooses a new value. I appreciate that you think you’ve discovered the answer here, but experience tells me it ain’t that simple.
Care to elaborate on why your experience tells you this?
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.
I think I gave one example: if the doc includes the rationale for the value, it needs to be updated.
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. ;)
I explicitly said not to write “why” docs to explain specific value choices, but rather document the context around the setting, and what happens when the value is raised or lowered, and why you might want to do that, so I’m thinking this isn’t a topic you’re grasping very well.
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 explicitly said sometimes you want to write about the rationale. I didn’t actually realize you were attempting to dictate that that wasn’t allowed. That seems pretty nuts.
And I think people who read Clean Code and aren’t dogmatic and condescending about trivial choices like this are pretty fine.
What you want and what is the best way to communicate are not always aligned.
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.
