Ask HN: Opinions about commentary in Golang

[shivylp]

Go convention is to write comments for every entity in a package that is exposed (starts with an upper case letter). Even linter complains about not commenting. I have heard people argue over this saying some things shouldn't be commented if they're obvious enough.

I agree that obvious things don't really need a comment. But the problem of commenting only certain things as opposed to all things, is inconsistency across codebase. If new developer looks at the code and sees comments only at certain places, it might feel like the comments aren't trustworthy since there is no standard pattern. Also, I believe the term obvious itself is not objective (at the time of writing the code, most of the stuff are obvious)..

What do you all think ?

[jerf]

For pretty much the reasons you give, I comment everything the linter wants commented. Sometimes the comment is just "Read implements io.Reader." or "$STRUCT is only exposed publicly for encoding/json, you should not use it."

You may find more success posting this sort of thing at reddit.com/r/golang, or some other dedicated Go community.

[shivylp]

Thanks. You're right about posting somewhere.. Not a regular Reddit user. So didn't think of that..