1 2trace-cmd coding-style 3====================== 4 5The coding style of trace-cmd and the tracing libraries (libtracefs and 6libtraceevent) are very similar to the Linux kernel coding style: 7 8 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst 9 10Indentation 11=========== 12 13Tabs are used for the start of indentation (the '\t' character), and should be 14set to 8 characters. Spaces may be used at the end for continued lines where 15having the start of text line up to braces in the previous line is not 16divisible by 8. 17 18Max line width 19============== 20 21All lines should not be more than 100 characters in length. 22 23This is a guide, as readability is more important than breaking lines up into a 24hard limit. Ideally, strings should never be broken up except for where a new 25line is added. 26 27 printf("This is a line that may continue for a very long string.\n" 28 "This is another line, but after a new line\n"); 29 30But line breaks should not be: 31 32 printf("This is a line that may continue for a very" 33 "long string.\n This is another line," 34 "but after a new line\n"); 35 36Not only is the above not as readable as the first version, it is not 37even equivalent, because it is missing spaces between the line breaks. 38For this reason, finish the string on the same line, even if that string 39breaks the 100 character limit. 40 41Brackets and braces 42=================== 43 44For all conditionals, the braces start on the same line: 45 46 if (cond) { 47 } 48 49And the ending brace is at the same indentation as the conditional. 50 51 while (cond) { 52 } 53 54 do { 55 } while (cond); 56 57 for (i = 0; i < 10; i++) { 58 } 59 60The same is true for structures: 61 62 struct my_struct { 63 int field; 64 }; 65 66But for functions, the braces should start on the following line: 67 68 void my_function(void) 69 { 70 } 71 72 73It is also fine to not use braces for simple conditionals and loops. 74 75 if (!x) 76 y = x; 77 else 78 y = 1; 79 80 for (i = 0; i < 10; i++) 81 foo(i); 82 83 while (getline(&line, &size, fp) > 0) 84 printf("%s", line); 85 86But any complex or multiline conditional or loop should have braces even if it 87is allowed not to by the C language. 88 89 if (x) { 90 for (i = 0; i < 10; i++) 91 foo(i); 92 } else { 93 foo(1); 94 } 95 96Notice above that even though the else portion is simple, it too has braces as 97the else and if blocks should match. If one is required to have braces, they 98both should have braces. 99 100 101Spaces 102====== 103 104A single space should be used between C commands and their starting 105parenthesis. 106 107 if (x) 108 for (i = 0; i < 10; i++) 109 while (getline(&line, &size, fp) > 0) 110 111There should be no space between function or macros and the starting 112parenthesis. 113 114 foo(x) 115 IS_VALID(y) 116 117This includes prototypes and declarations. 118 119 void foo(int x) 120 121A space should be before and after assignment, comparison and algorithmic 122signs. 123 124 i = 0; 125 if (i < 10) 126 if (i == 5) 127 128 y = i + 10; 129 130 i += 5; 131 132For structures, use tabs to make all the fields line up nicely. 133 134 struct { 135 int foo; 136 int bar; 137 unsigned long long time; 138 }; 139 140Variable declarations 141===================== 142 143The order of variables that are declared, should first keep the same types 144together, but also should be ordered by their length such that the variables 145are ordered in an "upside-down Christmas tree" fashion where the length gets 146smaller. 147 148 int tracecmd_count_cpus(void) 149 { 150 static int once; 151 char buf[1024]; 152 int cpus = 0; 153 char *pbuf; 154 size_t *pn; 155 FILE *fp; 156 size_t n; 157 int r; 158 159The above shows that the order is done by length, and in the above example it 160also shows that "int cpu = 0;" is not grouped next to "int r;". As this is more 161of a guideline and made to be more aesthetic to the eye of the reader, both the 162above and is acceptable as below. 163 164 int tracecmd_count_cpus(void) 165 { 166 static int once; 167 char buf[1024]; 168 char *pbuf; 169 size_t *pn; 170 FILE *fp; 171 size_t n; 172 int cpus = 0; 173 int r; 174 175 176Unless variables are tightly related, it is expected that each variable be on 177its own line and not grouped by type. That is, 178 179 int r, cpus = 0; 180 181is to be discouraged, as the two variables are not related to each other. 182But if you had a bunch of counters: 183 184 int i, j, k; 185 186That would be fine, as the variables are all related as they are all for the 187same purpose (arbitrary counters). The same may go with pointers; 188 189 190 char *begin, *end; 191 192Comments 193======== 194 195Comments will use the "/* */" format and the C++ "//" style is discouraged. 196If a comment is on one line, keep the "/*" and "*/" on the same line: 197 198 /* This is a single line comment. */ 199 200If a comment spans more than one line, then have the "/*" on a separate line 201before the comment and the "*/" on a separate line at the end of the comment, 202and each line starts with a "*" where all the "*" line up with each other. 203 204 /* 205 * This is a multi line comment, where all the '*' 206 * will line up, and the text is on a separate line 207 * as the start and end markers. 208 */ 209 210 211Function documentation 212====================== 213 214All global functions (and especially any APIs) should have a function 215description in the form of "kernel doc": 216 217 https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html 218 219The form is: 220 221 /** 222 * function_name() - Brief description of function. 223 * @arg1: Describe the first argument. 224 * @arg2: Describe the second argument. 225 * One can provide multiple line descriptions 226 * for arguments. 227 * 228 * A longer description, with more discussion of the function function_name() 229 * that might be useful to those using or modifying it. Begins with an 230 * empty comment line, and may include additional embedded empty 231 * comment lines. 232 * 233 * The longer description may have multiple paragraphs. 234 * 235 * Context: Describes whether the function can sleep, what locks it takes, 236 * releases, or expects to be held. It can extend over multiple 237 * lines. 238 * Return: Describe the return value of function_name. 239 * 240 * The return value description can also have multiple paragraphs, and should 241 * be placed at the end of the comment block. 242 */ 243 244Structure layout 245================ 246 247This is more about compaction than coding style. When creating structures, be 248aware that if the fields are placed together without being sized by alignment, 249that the compiler will create "holes" in them. 250 251 struct { 252 int x; 253 char y; 254 unsigned long long f; 255 }; 256 257As int is 4 bytes in length, char is one byte, and unsigned long long is 8 258bytes. The compiler will try to naturally align them by their size, and will 259include padding (holes) inside the structure to do so. The above is equivalent 260to: 261 262 struct { 263 int x; 264 char y; 265 char padding[3]; 266 unsigned long long f; 267 }; 268 269It is best to try to organize the structure where there are no holes within 270them. 271 272 struct { 273 unsigned long long f; 274 int x; 275 char y; 276 }; 277 278The above is better formatting, even if there may be padding outside the 279structure, but the compiler will still have more flexibility to utilize the 280space outside the structure than what it can do within it. 281 282General 283======= 284 285As stated, this is a guide and may not be strictly enforced. The goal is to 286have consistent and readable code. In general, try to have the coding style 287match the surrounding code. 288