2 |
3 |
4 |
5 | # C³: Common Coding Conventions
6 |
7 | > Keep it simple and solid, let the toolchain be smart,
8 | > code correctness is the duty, readability the art.
9 |
10 |
11 | The goal of these conventions is to be concise, universal, and remarkable. It targets emerging code enthusiasts under time pressure and covers 7 topics:
12 |
13 | 1. [**General Clarifications**](#user-content-general-clarifications)
14 | ([Keep Consistency](#user-content-be-consistent-with-the-existent) •
15 | [Break rules](#user-content-break-rules-if-it-enhances-clarity) •
16 | [Improve Code](#user-content-leave-code-cleaner-than-you-found-it) •
17 | [Terms](#user-content-terminology))
18 | 2. [**Architecture**](#user-content-architecture)
19 | ([Low Coupling](#user-content-aim-for-low-coupling-between-classes) •
20 | [Coherent Abstraction](#user-content-aim-for-coherent-abstraction-levels))
21 | 3. [**Implementation**](#user-content-implementation)
22 | ([DRY](#user-content-dont-repeat-yourself-dry) •
23 | [Small Scopes](#user-content-keep-all-scopes-fileclassfunction-small-and-sorted) •
24 | [Express Ideas](#user-content-express-ideas-in-code-use-domain-specific-names) •
25 | [Sort Args](#user-content-sort-arguments-and-limit-them-to-0--4-per-call) •
26 | [Compose](#user-content-do-not-change-the-same-variable-in-steps-but-compose-once-from-parts))
27 | 4. [**Naming**](#user-content-naming)
28 | ([Pick One](#user-content-pick-one-word-for-one-concept) •
29 | [Bools](#user-content-boolean-variablesfunctions-should-have-a-ishascan-prefix) •
30 | [Subprograms](#user-content-naming-subprograms-procedurefunction) •
31 | [Types](#user-content-naming-types-classstructsubtypes) •
32 | [Variables](#user-content-naming-variables) •
33 | [Word Pairs](#user-content-use-word-pairs-opposites-antonyms))
34 | 5. [**Code Layout**](#user-content-code-layout)
35 | 6. [**Documentation**](#user-content-documentation)
36 | ([Comments](#user-content-write-brief-comments-of-high-quality) •
37 | [TODOs](#user-content-use-todo-and-fixme-tags) •
38 | [Readmes](#user-content-write-readme-files) •
39 | [Logging](#user-content-avoid-print-use-a-library-with-log-levels) •
40 | [File Headers](#user-content-write-file-headers-for-header-files) •
41 | [Docstrings](#user-content-use-docstrings-for-public-apis))
42 | 7. [**Languages**](#user-content-languages)
43 | ([Python](chapter/lang/python-guide.md) •
44 | [C](chapter/lang/c-guide.md) •
45 | [JavaScript](chapter/lang/javascript-guide.md))
46 |
47 |
48 |
49 | To follow this guide, you should already have heard about [Object Oriented Programming](https://www.educative.io/blog/object-oriented-programming) and know basic programming rules, such as writing loops and meaningful functions instead of copy pasting instructions.
50 |
51 |
52 |
53 |
54 |
55 | ## [General Clarifications](#user-content-general-clarifications)
56 |
57 | ### Be consistent with the existent.
58 |
59 | “Consistency with this guide is important. Consistency within a project
60 | is more important. Consistency within one module or function is the most
61 | important” [[PEP8]](#user-content-references).
62 |
63 |
64 |
65 | ### Break rules if it enhances clarity.
66 |
67 | Do not blindly follow this guide but think for yourself. The goal of
68 | software development is keeping the code complexity low. Period. None of
69 | the rules and fancy patterns matters if the code becomes impossible to maintain.
70 |
71 |
72 |
73 | ### Leave code cleaner than you found it.
74 |
75 | We all have seen bad code, we all have written bad code. Code tends to get messy over time.
76 | Therefore, do not only complain about bad code but improve it if you know how. If *you* don't care to do it, why should anyone else?
77 |
78 |
79 |
80 | ### Terminology
81 |
82 | To be universal, we group several concepts under these broad
83 | identifiers:
84 |
85 |
86 | * **Scope** = {Module, File, Namespace, Subprogram}
87 | * **Subprogram** = {Procedure, Function, Method}
88 | * **Type** = {Primitive, Collection, Struct, Class, ...}
89 | * **Collection** = {Array, List, Tuple, Dict, Map, ...}
90 |
91 |
92 |
93 |
94 |
95 |
96 | ## [Architecture](#user-content-architecture)
97 |
98 | To manage complexity, divide your software into smaller parts (scopes)
99 | such as modules, classes, and subprograms. Where to separate and where
100 | to connect scopes is the art of good architecture.
101 |
102 | Two common mistakes in architecture design are the creation of a monster class that has too many responsibilities and letting each class communicate with too many other classes:
103 |
104 | 
105 |
106 |
107 | Instead, limit the amount and direction of information exchange between classes and create larger architectures from the following building blocks:
108 |
109 | 
110 |
111 |
112 |
113 | ### Aim for low coupling between classes.
114 |
115 | You may have many classes but each class should communicate with as few
116 | others as possible. If any two classes communicate at all, they should
117 | exchange as little information as possible.
118 |
119 |
120 |
121 | ### Aim for coherent abstraction levels.
122 |
123 | Each scope should reflect a single coherent level of abstraction that
124 | corresponds to its hierarchy level [[ClCd]](#user-content-references). In your UML, abstraction should
125 | decrease from top to bottom. In your code, the deeper you are in a call
126 | tree, the more specific your instructions can be. Avoid state variables
127 | at high abstraction levels.
128 |
129 |
130 | | Bad ❌ | Better ✔ | Better ✔ |
| 134 | 135 | ```python 136 | engine.start() 137 | nStartUps += 1 138 | if fuelTank.isEmpty(): 139 | fuelGaugeUI.setRedLED() 140 | ``` 141 | | 142 | 143 | ```python 144 | engine.start() 145 | engine.runTest() 146 | warnings = engine.warnings() 147 | dashboard.show( warnings ) 148 | ``` 149 | | 150 | 151 | ```python 152 | sys.test(): 153 | engine.test(): 154 | sparkPlug.test(): 155 | testIgnition() 156 | ``` 157 | |
| Bad ❌ | Better ✔ |
| 244 | 245 | ```c 246 | makeCircle(double r, double x, double y) 247 | ``` 248 | 249 | | 250 | 251 | ```c 252 | makeCircle(Point center, double radius) 253 | ``` 254 | 255 | |
| Bad ❌ | Better ✔ |
| 273 | 274 | ```c 275 | totalIncome = 0 276 | // ... long code to get contract 277 | totalIncome += contract.salary 278 | // ... long code to access taxoffice 279 | totalIncome -= taxoffice[id].tax 280 | ``` 281 | 282 | | 283 | 284 | ```c 285 | Int totalIncome(employee){ 286 | salary = getSalary(employee) 287 | tax = getTax(employee) 288 | return (salary - tax) 289 | } 290 | ``` 291 | 292 | |
| Bad ❌ | Better ✔ |
| 380 | 381 | ```python 382 | score_list = [0] * scores 383 | for idx, val in score_list: 384 | score_list = val + 1 385 | ``` 386 | 387 | | 388 | 389 | ```python 390 | scores = [0] * numScores 391 | for idx, score in scores: 392 | scores[idx] = score + 1 393 | ``` 394 | 395 | |
| Bad ❌ | Better ✔ |
| 494 | 495 | ```python 496 | if t.h > NIGHT_H: # Check if night 497 | if ifr.sense(): # detect person 498 | turnLightOn() # set Pin 13 499 | lockLight(TIMEOUT) # TIMEOUT=5s 500 | ``` 501 | 502 | | 503 | 504 | ```python 505 | if (isNightTime() and isPersonPresent()): 506 | turnLightOn() 507 | lockLight(TIMEOUT) # avoid flickering 508 | ``` 509 | 510 | |