Hello. Does anyone have any thoughts on what constitutes good idiomatic practice when it comes to the letter case used in // single line comments or indeed in // Single line comments? I think that we can all agree that // SINGLE LINE COMMENTS are a bad thing! I would prefer lower case unless absolutely necessary since we are not trying to turn comments into full grammatically correct English (or whatever language you use, of course!) sentences, but what are your thoughts on this?
I am a bit ambivalent about this, and my comments reflect this.
// usually I write short comments in this way
// If comments get longer, I tend to switch to proper
// sentences. I do this especially with code that appears
// in my blog, as the comments get rendered to the side of
// the code (if the page is wide enough).
// AND I DON‘T LIKE SHOUTING AT ALL
I don‘t know if there is an idiomatic writing style for comments, I think what everyone would agree about is that godoc comments should always be proper sentences.
The more important point IMHO is when to add comments and when to better leave them out. A good rule of thumb is to comment the WHY and maybe also the WHAT of the code, but not the HOW (because the latter is what the code itself already does).
See also Nate Finch’s latest article where he discusses proper use of comments.
I take your point about the tendency of longer comments to lean towards more structured sentences. If I see a short comment then brevity and lower case always win for me, but I must admit that once a sentence becomes longer, the more my need to see grammatical correctness becomes stronger. Your point about the blog linkage is well made, as well.
1 Like
Did you also read this? https://golang.org/doc/effective_go.html#commentary
Explains how to get the best out of comnets for godoc (and also grep/code search.)
That’s useful info. Thanks!
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.