Commentary in golang


(Shivaprasad Bhat) #1

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 ?


(Kristoffer Berdal) #2

We write comments for everything in our code because those comments are used to generate documentation!

See https://blog.golang.org/godoc-documenting-go-code.

"Self-Documenting code via commenting is extremely nice to have :slight_smile:

Sometimes it’s easy to skip writing those comments, but I always go back and write them if anyone else is going to look at the code, or just for my own future reference. Coming back to my own code is much easier when it’s commented. What seems obvious in the moment is not obvious 11 months after when you have to fix some bug you have missed or are re-writing something you have not touched in a long time :slight_smile:


(Shivaprasad Bhat) #3

Exactly what I believe and mentioned in the post. Thanks.