github.com/pachyderm/pachyderm@v1.13.4/doc/docs/1.11.x/contributing/coding-conventions.md (about)

     1  # Coding Conventions
     2  
     3  All code in this repo should be written in Go, Shell or Make.  Exceptions are
     4  made for things under `examples` because we want to be able to give people
     5  examples of using the product in other languages. And for things like
     6  `doc/conf.py` which configures an outside tool we want to use for docs. However
     7  in choosing outside tooling we prefer tools that we can interface with entirely
     8  using Go. Go's new enough that it's not always possible to find such a tool so
     9  we expect to make compromises on this. In general you should operate under the
    10  assumption that code written in Go, Shell or Make is accessible to all
    11  developers of the project and code written in other languages is accessible to
    12  only a subset and thus represents a higher liability.
    13  
    14  ## Shell
    15  
    16  - https://google.github.io/styleguide/shell.xml
    17  - Scripts should work on macOS as well as Linux.
    18  
    19  ## Go
    20  
    21  Go has pretty unified conventions for style, we vastly prefer embracing these
    22  standards to developing our own.
    23  
    24  ### Stylistic Conventions
    25  
    26  - We have several Go checks that run as part of CI, those should pass. You can
    27  run them with `make lint`.
    28  - [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
    29  - [Effective Go](https://golang.org/doc/effective_go.html)
    30  - Command-line flags should use dashes, not underscores.
    31  - Naming
    32    - Please consider package name when selecting an interface name, and avoid redundancy.
    33    - e.g.: `storage.Interface` is better than `storage.StorageInterface`.
    34    - Do not use uppercase characters, underscores, or dashes in package names.
    35    - Unless there's a good reason, the `package foo` line should match the name
    36  of the directory in which the .go file exists.
    37    - Importers can use a different name if they need to disambiguate.
    38    - Locks should be called `lock` and should never be embedded (always `lock
    39  sync.Mutex`). When multiple locks are present, give each lock a distinct name
    40  following Go conventions - `stateLock`, `mapLock` etc.
    41  
    42  ### Testing Conventions
    43  
    44  - All new packages and most new significant functionality must come with test coverage
    45  - Avoid waiting for asynchronous things to happen (e.g. waiting 10 seconds and
    46  assuming that a service will be afterward). Instead you try, wait, retry, etc.
    47  with a limited number of tries. If possible use a method of waiting directly
    48  (e.g. 'flush commit' is much better than repeatedly trying to read from a
    49  commit).
    50  
    51  ### Go Modules/Third-Party Code
    52  
    53  - Go dependencies are managed with go modules (as of 07/11/2019).
    54  - To add a new package or update a package. Do:
    55    - `go get foo`
    56      or for a more specific version
    57      `go get foo@v1.2.3`, `go get foo@master`, `go get foo@e3702bed2`
    58    - import foo package to you go code as needed.
    59  - Note: Go modules requires you clone the repo outside of the `$GOPATH` or you must pass the `GO111MODULE=on` flag to any go commands. See wiki page on [activating module support](https://github.com/golang/go/wiki/Modules#how-to-install-and-activate-module-support)
    60  
    61  - See
    62  [The official go modules wiki](https://github.com/golang/go/wiki/Modules)
    63  for more info.
    64  
    65  ### Docs
    66  
    67  - PRs for code must include documentation updates that reflect the changes
    68  that the code introduces.
    69  
    70  - When writing documentation, follow the [Style Guide](docs-style-guide.md)
    71  conventions.
    72  
    73  - PRs that have only documentation changes, such as typos, is a great place
    74  to start and we welcome your help!
    75  
    76  - For most documentation  PRs, you need to `make assets` and push the new
    77  `assets.go` file as well.