opentelemetry-proto icon indicating copy to clipboard operation
opentelemetry-proto copied to clipboard

Consistent style for documentation comments

Open anuraaga opened this issue 4 years ago • 2 comments

I notice there are three patterns for comments

Go-style, repeating name in javadoc e.g. Sum represents the type
Starting with It, otherwise similar to go-style
Java-style, documenting behavior directly e.g. Represents the type of a metric

Should this be made consistent? I have a personal preference to Java-style for protos since I've seen that more in the past, but it looks like we use Go-style more here so consolidating on that would make sense too.

anuraaga avatar Aug 21 '20 03:08 anuraaga

Unfortunately the proto style guide does not define this :( https://developers.google.com/protocol-buffers/docs/style

bogdandrutu avatar Feb 15 '21 17:02 bogdandrutu

My preference also goes to Java-style (which does not prohibit using the Go-style if that's the best way to express the thought).

tigrannajaryan avatar Feb 16 '21 16:02 tigrannajaryan