Go Language Modularization

Internal

• Go Language

Overview

A standard organization of the files that are part of a project makes easier to share code with other people who also use the same standard. Go workspaces encourage such a standard.

Workspaces

The standard workspace layout is:

. 
├─ src
├─ pkg
└─ bin

This layout is recommended, but not enforced.

A workspace may contain multiple projects.

Define the relationship between workspace and the GOPATH variable.

Packages

A package is a group of related source files. A package can be imported by other packages. Always, there must be one package called main, which produces an executable as result of its compilation. Other packages do not produce executables as result of their compilation.

Must the package live in a directory with the same name?

Deplete, merge into this document and delete: Go Concepts - Packages

Idiomatic Package Conventions

Package names are generally given lowercase, single-word names. They should be short, concise and evocative, and it should provide context for their contents.

Package-exported names start with an uppercase character.

The contents of a package should be consistent with the name. If you start noticing that a package includes extra logic that has no relationship to the package name, consider exporting it as a separate one, or use a more descriptive package name.

Every package should have a comment describing its contents.

Also see:

Go Style

Declaring Packages

The main Package

The main package produces an executable as result of its compilation. The main package must have a function called main(), which is where the code execution starts. For more details see:

main()

The name of the source code file that declares the main() function does not matter. The following code, declared in a blue.go source file, placed in any directory, not necessarily in a main directory, produces an executable named blue:

package main

import "fmt"

func main() {
  fmt.Printf("hello\n")
}

go build ./blue.go
./blue
hello

Importing Packages

When a package is imported during compilation, the compiler searches directories specified by the GOROOT and GOPATH environment variables.

import Keyword

The import is a keyword use to access other packages.

import "fmt"

import (
	"bufio"
	"fmt"
	"os"
	"strings"
)

Relationship between Source Code Files and Packages

TODO: how do we add source code files to package? Is it a flat space? It is a hierarchy? What kind of names should the files use?

Standard library

Go comes with a set of "built-in" packages, which come with the Go development environment.

The content of the Standard library is available here: https://pkg.go.dev/std

The standard library is a good source of code examples, comments and style.

Standard library packages:

archive	atomic	bytes	container	database	encoding	errors
flag	fmt	io	ioutil	encoding/json	hash	log
math	net	os	path	reflect	regexp	runtime
slices	sort	strings	strconv	sync	text/template	time
unicode

Vendoring

"Vendoring" is the act of making a local copy of a third party package your project depends on. This copy is traditionally placed inside each project and then saved in the project repository.

Vendoring is using local copies of external dependencies to satisfy imports of those dependencies.

For a directory structure referred by GOPATH, code below a directory named "vendor" is importable only by code in the directory tree rooted at the parent of "vendor", and only using an import path that omits the prefix up to and including the vendor element.

Code in vendor directories deeper in the source tree shadows code in higher directories. Within the subtree rooted at foo, an import of "crash/bang" resolves to "foo/vendor/crash/bang", not the top-level "crash/bang". Code in vendor directories is not subject to import path checking.

When 'go get' checks out or updates a git repository, it now also updates submodules.

Vendor directories do not affect the placement of new repositories being checked out for the first time by 'go get': those are always placed in the main GOPATH, never in a vendor subtree.

Export

The functions and variable that start with a capital letter in a package get exported: somebody who imports the package can access the exported names, but not the "private" names, which start with lower case letter. "Hidden" names is also used in this situation. This is how encapsulation is implemented for packages.

In the following example:

package colors

var color string = "blue"

func GetColor() { 
  return color
}

the color variable is private to the package, but it can be accessed with the public GetColor() function.

Modules

Explain go.mod

Package as Namespace

Each package defines a namespace for its identifiers, which include variables, types (structs, interfaces), functions