Coding Guidelines

Code organization

Vanadium is spread across multiple git repositories. The [contributor installation] process arranges these repositories as follows (some repositories omitted, for brevity):

 $JIRI_ROOT
   .jiri_root        # Jiri utils and metadata
     bin             # Contributor tool binaries
     scripts/jiri    # Jiri command-line tool
   environment       # Platform-dependent configuration
   manifest          # Multi-repo configuration data
   release           # Source code
     go/src/v.io/v23 # Interfaces
     go/src/v.io/x   # Implementation
       devtools      # Contributor tool source code
       lib           # Developer libs
       ref           # Reference implementation of v23
     javascript      # JS interfaces and implementation
     projects        # Example apps
       playground    # Write/build/run v23 code on the web
       browser       # Vanadium namespace browser
       chat          # Chat program
   third_party       # Third-party code
   website           # Source for this site

Each repository has a README.md file summarizing its purpose. The manifest repository contains the configuration that describes this repository arrangement.

Things move around, so its best to examine your local installation for the latest arrangement.

Go

Use gofmt and suggestions from Effective Go.

Interfaces

Vanadium interfaces are defined in the go/src/v.io/v23 tree in files named model.go. For example, the file security/model.go holds security interface definitions.

Testing

A test for package foo should be in package foo_test. This way, tests can depend on anything they like without introducing cycles or affecting non-test binaries.

If a test must touch the internals of some package foo, that test can be in package foo, but must keep its dependencies to a minimum, and must have a name that ends with _internal_test.go.

Most tests should import the v.io/x/ref/test package and invoke its Init function in order to configure logging, random number generators etc. Doing so will assist in debugging failing tests. For example:

• The -vv and -vmodule flags can be used to control logging verbosity
• The seed of the random number generator is logged when running tests. This is useful when trying to reproduce failures that may not occur when the random number generator is seeded differently.

VDL

The vdl tool uses VDL files to generate files containing RPC stub code for various languages - Go, Java, JavaScript, etc.

VDL is not Go, but is modeled after Go, so VDL code should follow Go's style guidelines.

VDL files have a Go-like notion of packages. Go code generated from a VDL file must appear in a location that respects both the VDL file's package name and the value of GOPATH. In a Go-based project like Vanadium, the simplest way to accomplish this is to place VDL source files into the go/src tree at the location that the generated Go should be placed.

Shell

We prefer Go programs over shell scripts for jobs traditionally given to shell scripts.

If you must write a shell script, follow the Google Shell Style Guide.