undefined | Better HN

0 pointsarduinomancer4y ago0 comments

This would not work based on my experience

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

0 comments

TameAntelope4y ago

I think you missed what I said; there's no need to update the external doc just because you updated the value.

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.

hamburglar4y ago

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.

TameAntelope4y ago

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.

1 more reply

j / k navigate · click thread line to collapse

0 comments

TameAntelope4y ago

I think you missed what I said; there's no need to update the external doc just because you updated the value.

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.

hamburglar4y ago

TameAntelope4y ago

Care to elaborate on why your experience tells you this?

1 more reply

j / k navigate · click thread line to collapse