Coding Guidelines

Code organization

Vanadium is spread across multiple git repositories. The contributor installation process arranges these repositories as follows:

 $JIRI_ROOT
   devtools          # Contributor tools
   environment       # Platform dependent configuration
   .manifest         # Multi-repo control data
   release           # Source code
     go/src/v.io/v23 # Interfaces
     go/src/v.io/x   # Implementation
       devtools      # Contributor tool source
       lib           # Developer libs
       ref           # Reference implementation of v23
     javascript      # JS compatibility
     projects        # Example apps
       playground    # Write/build/run v23 code on web
       browser       # Vanadium namespace browser
       chat          # Chat program
   scripts           # Contributor scripts
   third_party       # Third party code
   www               # Source for this site

Each repository has a README file summarizing its purpose. The devtools directory isn't a repository, but rather a top level directory where contributor tools are placed during installation. 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 devtools/bin/vdl tool uses VDL files to generate files containing RPC stub code for various languages - Go, 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.

JavaScript

Follow the Node.js Style Guide. Use our .jshintrc.

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.