doc: filename conventions

[carnott-snap]

If I have simply missed where this is documented, please let me know where I should have looked, and close this out.

Many places describe how custom filename suffixes interact with the toolchain: _test, _linux, _arm. However I cannot find anywhere that says you should use snake case for multi-word file names, as is suggested by the standard library: e.g. time/zoneinfo_read.go/os/removeall_at.go not time/zoneinfoRead.go/os/removeallAt.go or time/zoneinfo-read.go/os/removeall-at.go.

This may seem self evident to experienced users, but I have seen many people get confused by the fact that variables use CamelCase := "", while files use snake_case.go.

[toothrot]

I am not certain where this convention is documented, but I feel like @ianlancetaylor or @bradfitz might have some guidance.

[dmitshur]

To my knowledge, there isn't a documented convention for .go file names (other than meaningful things like _test.go, leading . or _, trailing _goos_goarch, etc.) anywhere. I've checked https://golang.org/doc/effective_go.html and https://golang.org/s/style.

The Go project itself tends to prefer short names like io.go, pipe.go, etc. In the rare cases two words are needed, they are joined without an underscore, like cputicks.go or debugcall.go. For more complicated packages with many files, underscores are sometimes used when additional separation is needed.

[carnott-snap]

That is useful to note. It led me down a bit of a rabbit hole, and it looks like even the standard library is not consistent (though lowercasealloneword seems to be in the plurality). Should we make a standard?

file.extension.go

out:
- cmd/internal/obj/arm/a.out.go
- cmd/internal/obj/arm64/a.out.go
- cmd/internal/obj/mips/a.out.go
- cmd/internal/obj/ppc64/a.out.go
- cmd/internal/obj/s390x/a.out.go
- cmd/internal/obj/wasm/a.out.go
- cmd/internal/obj/x86/a.out.go

snake_case.go

marshaling:
- encoding/json/example_marshaling_test.go
- encoding/json/example_text_marshaling_test.go
- encoding/xml/example_marshaling_test.go
- encoding/xml/example_text_marshaling_test.go
mmap:
- cmd/compile/internal/gc/mapfile_mmap.go
- cmd/internal/bio/buf_mmap.go
- cmd/link/internal/ld/outbuf_mmap.go
- runtime/cgo_mmap.go
- runtime/export_mmap_test.go
- runtime/runtime_mmap_test.go
string:
- cmd/compile/internal/gc/class_string.go
- cmd/compile/internal/gc/op_string.go
- cmd/compile/internal/syntax/operator_string.go
- cmd/compile/internal/syntax/token_string.go
- cmd/compile/internal/types/etype_string.go
- cmd/internal/obj/abi_string.go
- cmd/internal/obj/addrtype_string.go
- cmd/internal/objabi/reloctype_string.go
- cmd/internal/objabi/symkind_string.go
- cmd/link/internal/sym/symkind_string.go
- debug/dwarf/attr_string.go
- debug/dwarf/class_string.go
- debug/dwarf/tag_string.go
- debug/macho/reloctype_string.go
- html/template/attr_string.go
- html/template/delim_string.go
- html/template/element_string.go
- html/template/jsctx_string.go
- html/template/state_string.go
- html/template/urlpart_string.go
- math/big/accuracy_string.go
- math/big/roundingmode_string.go
- regexp/syntax/op_string.go
sysnum:
- internal/syscall/unix/at_sysnum_darwin.go
- internal/syscall/unix/at_sysnum_dragonfly.go
- internal/syscall/unix/at_sysnum_fstatat64_linux.go
- internal/syscall/unix/at_sysnum_fstatat_linux.go
- internal/syscall/unix/at_sysnum_linux.go
- internal/syscall/unix/at_sysnum_netbsd.go
- internal/syscall/unix/at_sysnum_newfstatat_linux.go
- internal/syscall/unix/at_sysnum_openbsd.go

lowercase.go

gccgoinstallation:
- go/internal/gccgoimporter/gccgoinstallation_test.go
loopreschedchecks:
- cmd/compile/internal/ssa/loopreschedchecks.go
mkfastlog2table:
- runtime/mkfastlog2table.go
mksizeclasses:
- runtime/mksizeclasses.go
obscuretestdata:
- internal/obscuretestdata/obscuretestdata.go
reproduciblebuilds:
- cmd/compile/internal/gc/reproduciblebuilds_test.go

CamelCase.go

386Ops:
- cmd/compile/internal/ssa/gen/386Ops.go
"387":
- cmd/compile/internal/x86/387.go
AMD64Ops:
- cmd/compile/internal/ssa/gen/AMD64Ops.go
ARM64Ops:
- cmd/compile/internal/ssa/gen/ARM64Ops.go
ARMOps:
- cmd/compile/internal/ssa/gen/ARMOps.go
MIPS64Ops:
- cmd/compile/internal/ssa/gen/MIPS64Ops.go
MIPSOps:
- cmd/compile/internal/ssa/gen/MIPSOps.go
PPC64Ops:
- cmd/compile/internal/ssa/gen/PPC64Ops.go
S390XOps:
- cmd/compile/internal/ssa/gen/S390XOps.go
WasmOps:
- cmd/compile/internal/ssa/gen/WasmOps.go
arithBoundary:
- cmd/compile/internal/gc/testdata/arithBoundary_test.go
arithBoundaryGen:
- cmd/compile/internal/gc/testdata/gen/arithBoundaryGen.go
arithConst:
- cmd/compile/internal/gc/testdata/arithConst_test.go
arithConstGen:
- cmd/compile/internal/gc/testdata/gen/arithConstGen.go
deferNoReturn:
- cmd/compile/internal/gc/testdata/deferNoReturn_test.go

[ianlancetaylor]

Although the compiler made a different choice, for the standard library we've historically preferred all lowercase just to avoid confusion on case-insensitive systems. I don't know that this is written down anywhere. I don't know that we have any particular guidance for file names in packages outside the standard library.

[dmitshur]

I don't know that we have any particular guidance for file names in packages outside the standard library.

To make progress on this issue, we need to decide if we should change that and attempt to offer guidance by adding an entry to https://golang.org/doc/effective_go.html or https://golang.org/s/style, or if we should not.

At this time, I'm inclined to believe we should not.

People who care about this can look at the .go file naming strategies used by the Go standard library and mimic it. Those who don't care can choose a naming strategy that they prefer.

There are additional resources where people write down their opinions on Go style, such as those listed at https://medium.com/@dgryski/idiomatic-go-resources-966535376dba. Perhaps an entry in one of those lists would be more viable.

[carnott-snap]

I opened this issue because I have colleagues that asked, what filename conventions should I use with go?

I can understand that trying to stabilise this now may be problematic, noisy, or too late. But the lack of consensus will cause some amount of confusion and cognitive overhead. Because the community (seems to) understand the benefits of standardisation, see gofmt, even a soft recommendation in a blog post would go a long way.

[peterbourgon]

There is a de facto standard for Go source file names: all lowercase with underscore separation when necessary, i.e. snake case. (The exceptions are exceptions.) I'd appreciate having it as a documented standard, too, to answer questions like @carnott-snap notes, especially among junior Gophers. In my opinion it needn't be so formal as entering Effective Go, a short new section on CodeReviewComments is more than sufficient.

File names

Go source file names should be lowercase_with_underscores.go and not camelCase.go or TitleCase.go. This makes them consistent with other language conventions, like _test.go for test files, or _windows.go for build constraints. It also prevents ambiguities on case-insensitive file systems.