undefined | Better HN

0 pointsjonahx4y ago0 comments

>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.

0 comments

TameAntelope4y 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.

hamburglar4y 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.

jonahxOP4y ago

I am saying things like this:

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.

TameAntelope4y 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.

j / k navigate · click thread line to collapse

0 comments

TameAntelope4y 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.

hamburglar4y 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.

jonahxOP4y ago

I am saying things like this:

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.

TameAntelope4y 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.

j / k navigate · click thread line to collapse