github.com/uber/kraken@v0.1.4/docs/STYLEGUIDE.md (about)

     1  ## Code style guidelines
     2  
     3  This project adheres to the official Go style guidelines: https://github.com/golang/go/wiki/CodeReviewComments
     4  
     5  Some things we are very picky about:
     6  
     7  #### Variable naming
     8  
     9  Please read: https://talks.golang.org/2014/names.slide#1
    10  
    11  #### Comments
    12  
    13  All comments, regardless of location, must have proper grammar, including proper capitalization and punctuation.
    14  
    15  ```
    16  // this is a bad comment with bad grammar
    17  
    18  // This is a good comment with good grammar.
    19  ```
    20  
    21  Avoid comments that state the obvious or repeat code logic. Comments can easily get out of sync with
    22  the code and can mislead rather than help.
    23  
    24  #### Line length
    25  
    26  All lines of code should be kept under 100 characters.
    27  
    28  Comments should be kept under 80 characters.
    29  
    30  #### Breaking up long lines
    31  
    32  Long function signatures should be broken up like so:
    33  
    34  ```
    35  func Foo(
    36      bar int,
    37      baz bool,
    38      blah []int) (string, error) {
    39    
    40      ...
    41  }
    42  ```
    43   
    44  And callsites:
    45   
    46  ```
    47  // If it fits on a 2nd line:
    48  x, err := Foo(
    49      1, false, []int{1, 2, 3})
    50      
    51  // If it doesn't:
    52  y, err := Foo(
    53      1,
    54      false,
    55      []int{1, 2, 3, ...})
    56  ```
    57  
    58  #### Whitespace
    59  
    60  Be conservative with adding blank lines between blocks of code. Avoid cluttering vertical screen space
    61  with blank lines when the code reads just fine without them.
    62  
    63  Bad:
    64  
    65  ```
    66  func (s *State) DeletePending(peerID core.PeerID, h core.InfoHash) {
    67  	k := connKey{peerID, h}
    68    
    69  	if !s.pending[k] {
    70  		return
    71  	}
    72    
    73  	delete(s.pending, k)
    74    
    75  	s.capacity[k.infoHash]++
    76  
    77  	s.log("peer", peerID, "hash", h).Infof(
    78  		"Deleted pending conn, capacity now at %d", s.capacity[k.infoHash])
    79  }
    80  ```
    81  
    82  Good:
    83  
    84  ```
    85  func (s *State) DeletePending(peerID core.PeerID, h core.InfoHash) {
    86  	k := connKey{peerID, h}
    87  	if !s.pending[k] {
    88  		return
    89  	}
    90  	delete(s.pending, k)
    91  	s.capacity[k.infoHash]++
    92  
    93  	s.log("peer", peerID, "hash", h).Infof(
    94  		"Deleted pending conn, capacity now at %d", s.capacity[k.infoHash])
    95  }
    96  ```