gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/g3doc/style.md (about)

     1  # Provisional style guide
     2  
     3  > These guidelines are new and may change. This note will be removed when
     4  > consensus is reached.
     5  
     6  Not all existing code will comply with this style guide, but new code should.
     7  Further, it is a goal to eventually update all existing code to be in
     8  compliance.
     9  
    10  ## All code
    11  
    12  ### Early exit
    13  
    14  All code, unless it substantially increases the line count or complexity, should
    15  use early exits from loops and functions where possible.
    16  
    17  ## Go specific
    18  
    19  All Go code should comply with the [Go Code Review Comments][gostyle] and
    20  [Effective Go][effective_go] guides, as well as the additional guidelines
    21  described below.
    22  
    23  ### Mutexes
    24  
    25  #### Naming
    26  
    27  Mutexes should be named mu or xxxMu. Mutexes as a general rule should not be
    28  exported. Instead, export methods which use the mutexes to avoid leaky
    29  abstractions.
    30  
    31  #### Location
    32  
    33  Mutexes should be sibling fields to the fields that they protect. Mutexes should
    34  not be declared as global variables, instead use a struct (anonymous ok, but
    35  naming conventions still apply).
    36  
    37  Mutexes should be ordered before the fields that they protect.
    38  
    39  #### Comments
    40  
    41  Mutexes should have a comment on their declaration explaining any ordering
    42  requirements (or pointing to where this information can be found), if
    43  applicable. There is no need for a comment explaining which fields are
    44  protected.
    45  
    46  Each field or variable protected by a mutex should state as such in a comment on
    47  the field or variable declaration.
    48  
    49  ### Function comments
    50  
    51  Functions with special entry conditions (e.g., a lock must be held) should state
    52  these conditions in a `Preconditions:` comment block. One condition per line;
    53  multiple conditions are specified with a bullet (`*`).
    54  
    55  Functions with notable exit conditions (e.g., a `Done` function must eventually
    56  be called by the caller) can similarly have a `Postconditions:` block.
    57  
    58  ### Unused returns
    59  
    60  Unused returns should be explicitly ignored with underscores. If there is a
    61  function which is commonly used without using its return(s), a wrapper function
    62  should be declared which explicitly ignores the returns. That said, in many
    63  cases, it may make sense for the wrapper to check the returns.
    64  
    65  ### Formatting verbs
    66  
    67  Built-in types should use their associated verbs (e.g. %d for integral types),
    68  but other types should use a %v variant, even if they implement fmt.Stringer.
    69  The built-in `error` type should use %w when formatted with `fmt.Errorf`, but
    70  only then.
    71  
    72  ### Wrapping
    73  
    74  Comments should be wrapped at 80 columns with a 2 space tab size.
    75  
    76  Code does not need to be wrapped, but if wrapping would make it more readable,
    77  it should be wrapped with each subcomponent of the thing being wrapped on its
    78  own line. For example, if a struct is split between lines, each field should be
    79  on its own line.
    80  
    81  #### Example
    82  
    83  ```go
    84  _ = exec.Cmd{
    85    Path: "/foo/bar",
    86    Args: []string{"-baz"},
    87  }
    88  ```
    89  
    90  ## C++ specific
    91  
    92  C++ code should conform to the [Google C++ Style Guide][cppstyle] and the
    93  guidelines described for tests.
    94  
    95  [cppstyle]: https://google.github.io/styleguide/cppguide.html
    96  [gostyle]: https://github.com/golang/go/wiki/CodeReviewComments
    97  [effective_go]: https://golang.org/doc/effective_go.html