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

all: usage of backticks and single quotes in the codebase #41958

Closed
shmsr opened this issue Oct 13, 2020 · 3 comments
Closed

all: usage of backticks and single quotes in the codebase #41958

shmsr opened this issue Oct 13, 2020 · 3 comments
Labels
Milestone

Comments

@shmsr
Copy link
Contributor

@shmsr shmsr commented Oct 13, 2020

What version of Go are you using (go version)?

$ go version
go version go1.15.2 darwin/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

Operating System: Mac OS Catalina
Arch: amd64

go env Output
$ go env
GO111MODULE=""
GOARCH="amd64"
GOBIN=""
GOCACHE="/Users/subhamsarkar/Library/Caches/go-build"
GOENV="/Users/subhamsarkar/Library/Application Support/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOINSECURE=""
GOMODCACHE="/Users/subhamsarkar/go/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="darwin"
GOPATH="/Users/subhamsarkar/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/usr/local/Cellar/go/1.15.2/libexec"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/usr/local/Cellar/go/1.15.2/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
AR="ar"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/n2/w00w99g93cj26xl42msl6lc80000gp/T/go-build872030515=/tmp/go-build -gno-record-gcc-switches -fno-common"

What did you do?

I was reading the documented for Ticker and I noticed that:

A Ticker holds a channel that delivers `ticks' of a clock at intervals.

Notice that "ticks" is enclosed between <backtick> and <single-quote>.

Reference to a similar issue from the issue tracker: #30955
Also, refer to this commit

I'm using BSD's grep with the regex "\x20`[^(`')]+'\x20" to find similar patterns in the codebase and I even could find some.

$ grep -r -E "\x20\`[^(\`\')]+\'\x20" /usr/local/Cellar/go/1.15.2/libexec/src

/usr/local/Cellar/go/1.15.2/libexec/src/cmd/go/go_test.go:	tg.grepStderr("^hello world", `ldflags -X "main.extern=hello world"' failed`)
/usr/local/Cellar/go/1.15.2/libexec/src/cmd/vendor/golang.org/x/mod/module/module.go:// (The excluded punctuation characters, " * < > ? ` ' | / \ and :,
/usr/local/Cellar/go/1.15.2/libexec/src/compress/bzip2/bzip2.go:	c            [256]uint // the `C' array for the inverse BWT.
/usr/local/Cellar/go/1.15.2/libexec/src/compress/bzip2/bzip2.go:	tt           []uint32  // mirrors the `tt' array in the bzip2 source and contains the P array in the upper 24 bits.
/usr/local/Cellar/go/1.15.2/libexec/src/compress/bzip2/bzip2.go:	// The `C' array (used by the inverse BWT) needs to be zero initialized.
/usr/local/Cellar/go/1.15.2/libexec/src/compress/bzip2/bzip2.go:// In that document, origPtr is called `I' and c is the `C' array after the
/usr/local/Cellar/go/1.15.2/libexec/src/compress/bzip2/bzip2.go:// This also implements the `single array' method from the bzip2 source code
/usr/local/Cellar/go/1.15.2/libexec/src/archive/tar/writer_test.go:		//	gnutar: Substituting `.' for empty member name
/usr/local/Cellar/go/1.15.2/libexec/src/archive/tar/writer_test.go:		//	gnutar: Substituting `.' for empty member name
/usr/local/Cellar/go/1.15.2/libexec/src/encoding/gob/encoder_test.go:		t.Fatal("round 3: expected `bad type' error decoding ET2")
/usr/local/Cellar/go/1.15.2/libexec/src/time/tick.go:// A Ticker holds a channel that delivers `ticks' of a clock

(Note: There are some false positives as well)

So, I think we should either change

`<text>'

to

'<text>'

or

``<text>''

Although I know the history behind the usage of backticks and single quote but I still think that we should update it.
Also, it seems like a very small change but if it's to be considered then I'd like to send a CL for the same.

What did you expect to see?

$ go doc time.Ticker

package time // import "time"

type Ticker struct {
	C <-chan Time // The channel on which the ticks are delivered.
	// Has unexported fields.
}
    A Ticker holds a channel that delivers “ticks” of a clock at intervals.

func NewTicker(d Duration) *Ticker
func (t *Ticker) Reset(d Duration)
func (t *Ticker) Stop()

or

$ go doc time.Ticker

package time // import "time"

type Ticker struct {
	C <-chan Time // The channel on which the ticks are delivered.
	// Has unexported fields.
}
    A Ticker holds a channel that delivers 'ticks' of a clock at intervals.

func NewTicker(d Duration) *Ticker
func (t *Ticker) Reset(d Duration)
func (t *Ticker) Stop()

What did you see instead?

$ go doc time.Ticker

package time // import "time"

type Ticker struct {
	C <-chan Time // The channel on which the ticks are delivered.
	// Has unexported fields.
}
    A Ticker holds a channel that delivers `ticks' of a clock at intervals.

func NewTicker(d Duration) *Ticker
func (t *Ticker) Reset(d Duration)
func (t *Ticker) Stop()
@ianlancetaylor
Copy link
Contributor

@ianlancetaylor ianlancetaylor commented Oct 13, 2020

@rsc
Copy link
Contributor

@rsc rsc commented Oct 14, 2020

It is fine to change the ones here meant as quotes in doc comments to `` and ''.
The ones outside doc comments are harmless and can be left as is.

@gopherbot
Copy link

@gopherbot gopherbot commented Oct 14, 2020

Change https://golang.org/cl/262397 mentions this issue: all: fix quoting for compress/bzip2 and time's godoc

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
5 participants
You can’t perform that action at this time.