Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/website: Orientation about trailing dots in comments on the Effective Go website #40259

Closed
rogerlucena opened this issue Jul 16, 2020 · 1 comment

Comments

@rogerlucena
Copy link

rogerlucena commented Jul 16, 2020

What did you do?

In your Effective Go website you set a standard of indeed using trailing dots by the end of comments on the "Commentary" section, as shown below:

// Compile parses a regular expression and returns, if successful,
// a Regexp that can be used to match against text.
func Compile(str string) (*Regexp, error) {

But just above it, in the "Formatting" section, you write brief comments without dots by the end:

type T struct {
    name string // name of the object
    value int // its value
}

What is the Go readability standard then?

What did you expect to see?

A standardized way of writing comments in Go with regards to trailing dots.

What did you see instead?

Two different ways inside your Effective Go website.

@gopherbot gopherbot added this to the Unreleased milestone Jul 16, 2020
@andybons
Copy link
Member

andybons commented Jul 16, 2020

As stated in Effective Go, doc comments (the first type you mention) work best as complete sentences, which implies a period at the end.

We make no recommendation for end-of-line comments (the second example you provide).

Since Effective Go is frozen at the point, we are unlikely to change this.

Our advice is to remain consistent with the code around you and/or follow your team’s style guides.

@golang golang locked and limited conversation to collaborators Jul 16, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

3 participants