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
Milestone

Comments

@rogerlucena
Copy link

@rogerlucena 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 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.

@andybons andybons closed this Jul 16, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants
You can’t perform that action at this time.