4 ms·

You 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

You 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 ago
  It'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 ago
    I 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 ago
    I 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.
    - TameAntelope 5y ago
      If you think variable naming is the only tool in the “self documenting code” toolbox, I recommend learning substantially more before dismissing the concept.
arduinomancer 5y ago
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
- TameAntelope 5y 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.
  - hamburglar 5y 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.
    - TameAntelope 5y 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.
      - hamburglar 5y ago
        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. ;)

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 ago
It'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 ago
  I 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 ago
  I 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.
  - TameAntelope 5y ago
    If you think variable naming is the only tool in the “self documenting code” toolbox, I recommend learning substantially more before dismissing the concept.

arduinomancer 5y ago

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

TameAntelope 5y 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.
- hamburglar 5y 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.
  - TameAntelope 5y 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.
    - hamburglar 5y ago
      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. ;)