github.com/kiali/kiali@v1.84.0/STYLE_GUIDE.adoc (about)

     1  = Code Style Guide
     2  :toc: macro
     3  :toc-title:
     4  
     5  toc::[]
     6  
     7  == Backend - Go
     8  
     9  The backend is written in link:https://golang.org/[Go]. If you are not familiar with it, you can take link:https://tour.golang.org/welcome/1[a Tour of Go].
    10  
    11  In Kiali we use link:https://golang.org/cmd/gofmt/[gofmt] as part of our build process to keep a consistent formatting.
    12  
    13  While we haven't automated static code analysers, it is still a good idea to check that new pieces of code are correct with tools such as link:https://github.com/golang/lint[golint] or link:https://golang.org/cmd/vet/[govet].
    14  
    15  === Imports
    16  
    17  If you need any library you should import them in the following format
    18  
    19  ----
    20  <standard imports>
    21  LINE
    22  <third party imports>
    23  LINE
    24  <kiali imports>
    25  ----
    26  
    27  Example:
    28  
    29  [source,go]
    30  ----
    31  import (
    32  	"errors"
    33  	"fmt"
    34  	"time"
    35  
    36  	"k8s.io/client-go/tools/clientcmd/api"
    37  
    38  	"github.com/kiali/kiali/log"
    39  )
    40  ----
    41  
    42  == Frontend - TypeScript
    43  
    44  === Default conventions
    45  
    46  By default, we try to follow community conventions. link:https://github.com/basarat/typescript-book/blob/master/docs/styleguide/styleguide.md[Basarat's Style Guide] is used as a reference, with a few exceptions that are listed below:
    47  
    48  ==== File names
    49  
    50  Most files are named after the main type / class / interface it's exporting. For instance, `ServiceList.ts` is named after the `ServiceList` interface that it's exporting. Which means that, unlike in Basarat's guide, we often use `PascalCase`.
    51  
    52  Files with more general purpose, or the ones that don't export types or such, are `camelCase` (ex: `routes.ts`).
    53  
    54  ==== Variables, functions, constants
    55  
    56  We mostly follow Basarat's guide, so `camelCase`. Exceptions are:
    57  
    58  - Redux actions, which are technically constants, are `PascalCase` (ex: `GraphActions`).
    59  - We sometimes make a difference between constants of global scopes versus constants of local scopes. You may find the former written in `UPPER_SNAKE_CASE` (ex: `const TIMER_REQUEST_PER_SECOND_MIN = 0;`), whereas Basarat's guide makes no distinction between different kinds of constants, all of them being `camelCase`.
    60  
    61  ==== Enum
    62  
    63  Enum names follow Basarat's guide, but not the values: they are `UPPER_SNAKE_CASE`. Example:
    64  
    65  [source,typescript]
    66  ----
    67  enum DisplayMode {
    68    LARGE,
    69    SMALL
    70  }
    71  ----
    72  
    73  === Handlers
    74  
    75  Use consistent naming for events and event handlers: name the handler methods after their triggering event.
    76  
    77  Event handlers should:
    78  
    79  * begin with handle
    80  * end with the name of the event they handle (eg, Click, Change)
    81  * be present-tense
    82  
    83  Event names:
    84  
    85  * in props should start with on
    86  * should not clash with builtin/native event names, eg. use onSelect instead of onFocus or onClick
    87  
    88  === Use arrow functions (fat arrow)
    89  
    90  [source,typescript]
    91  ----
    92  createItem = () => {
    93      return (
    94        <ul>
    95          {props.items.map((item, index) => (
    96            <Item
    97              key={item.key}
    98              onClick={() => doSomethingWith(item.name, index)}
    99            />
   100          ))}
   101        </ul>
   102      );
   103  }
   104  ----
   105  
   106  === Redux
   107  
   108  ==== Type-safe usage
   109  
   110  For additional type safety in our Redux Actions/Reducers, we use the library:
   111  https://github.com/piotrwitek/typesafe-actions
   112  Please refer to this site for instructions on how to use typescript with Redux.
   113  
   114  ==== URL Consistency
   115  
   116  Every application page should strive to have it's state in Redux so that
   117  we have a reproducible application state contained in Redux.
   118  To this end, we also want pages to be bookmarkable via URL. The URL and its
   119  parameters become the API for the page. And, the Redux application state should
   120  be able to be mutated via the URL parameters. In order to support this, here are some
   121  of the rules needed:
   122  
   123  * On component construction let URL param values override any existing redux state values.
   124  * On component construction set (via replace) any unset URL params to reflect the redux state value. This gives us a full bookmark at all times.
   125  * After construction update URL (via replace) as necessary to reflect redux state changes. This is typically done in _componentDidUpdate_. This maintains the full bookmark.
   126  
   127  ==== Redux props usage
   128  
   129  The declaration of the properties of a component connected to Redux should clearly indicate whether each property comes from Redux or are strictly from the component.
   130  This convention should help developers easily see which properties comes from the Redux state management without the need to be either versed with the whole Redux catalog or the component itself.
   131  
   132  The convention is consist in:
   133  
   134  * Declaring a type `ReduxProps` which only contains the Redux properties, sorted alphabetically.
   135  * Declaring a type `<ClassName>Props` which only contains the properties from the component, sorted alphabetically.
   136  * Intersecting type `ReduxProps` into type `<ClassName>Props`.
   137  * Using `<ClassName>Props` type for the component declaration.
   138  
   139  See an example:
   140  
   141  [source, typescript]
   142  ----
   143  type ReduxProps = {
   144   // just the Redux props, alphabetical
   145  };
   146  
   147  type <ClassName>Props = ReduxProps & {
   148   // non-Redux props, alphabetical
   149  };
   150  
   151  class <ClassName>Component extends React.Component<Props> {
   152  ...
   153  }
   154  ----