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 ----