|
| 1 | +# Coding Style for Apache Mynewt Core |
| 2 | + |
| 3 | +This document is meant to define the coding style for Apache Mynewt, and |
| 4 | +all subprojects of Apache Mynewt. This covers C and Assembly coding |
| 5 | +conventions, *only*. Other languages (such as Go), have their own |
| 6 | +coding conventions. |
| 7 | + |
| 8 | +## Headers |
| 9 | + |
| 10 | +* All files that are newly written, should have the Apache License clause |
| 11 | +at the top of them. |
| 12 | + |
| 13 | +* For files that are copied from another source, but contain an Apache |
| 14 | +compatible license, the original license header shall be maintained. |
| 15 | + |
| 16 | +* For more information on applying the Apache license, the definitive |
| 17 | +source is here: http://www.apache.org/dev/apply-license.html |
| 18 | + |
| 19 | +* The Apache License clause for the top of files is as follows: |
| 20 | + |
| 21 | +```no-highlight |
| 22 | +/* |
| 23 | + * Licensed to the Apache Software Foundation (ASF) under one |
| 24 | + * or more contributor license agreements. See the NOTICE file |
| 25 | + * distributed with this work for additional information |
| 26 | + * regarding copyright ownership. The ASF licenses this file |
| 27 | + * to you under the Apache License, Version 2.0 (the |
| 28 | + * "License"); you may not use this file except in compliance |
| 29 | + * with the License. You may obtain a copy of the License at |
| 30 | + * |
| 31 | + * http://www.apache.org/licenses/LICENSE-2.0 |
| 32 | + * |
| 33 | + * Unless required by applicable law or agreed to in writing, |
| 34 | + * software distributed under the License is distributed on an |
| 35 | + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 36 | + * KIND, either express or implied. See the License for the |
| 37 | + * specific language governing permissions and limitations |
| 38 | + * under the License. |
| 39 | + */ |
| 40 | +``` |
| 41 | + |
| 42 | +## Whitespace and Braces |
| 43 | + |
| 44 | +* Code must be indented to 4 spaces, tabs should not be used. |
| 45 | + |
| 46 | +* Do not add whitespace at the end of a line. |
| 47 | + |
| 48 | +* Put space after keywords (for, if, return, switch, while). |
| 49 | + |
| 50 | +* for, else, if, while statements must have braces around their |
| 51 | +code blocks, i.e., do: |
| 52 | + |
| 53 | +``` |
| 54 | + if (x) { |
| 55 | + assert(0); |
| 56 | + } else { |
| 57 | + assert(0); |
| 58 | + } |
| 59 | +``` |
| 60 | + |
| 61 | +Not: |
| 62 | + |
| 63 | +``` |
| 64 | + if (x) |
| 65 | + assert(0); |
| 66 | + else |
| 67 | + assert(0); |
| 68 | +``` |
| 69 | + |
| 70 | +* Braces for statements must be on the same line as the statement. Good: |
| 71 | + |
| 72 | +``` |
| 73 | + for (i = 0; i < 10; i++) { |
| 74 | + if (i == 5) { |
| 75 | + break; |
| 76 | + } else { |
| 77 | + continue; |
| 78 | + } |
| 79 | + } |
| 80 | +``` |
| 81 | + |
| 82 | +Not: |
| 83 | + |
| 84 | +``` |
| 85 | + for (i = 0; i < 10; i++) |
| 86 | + { <-- brace must be on same line as for |
| 87 | + if (i == 5) { |
| 88 | + break; |
| 89 | + } <-- no new line between else |
| 90 | + else { |
| 91 | + continue; |
| 92 | + } |
| 93 | + } |
| 94 | +``` |
| 95 | + |
| 96 | +* After a function declaration, the braces should be on a newline, i.e. do: |
| 97 | + |
| 98 | +``` |
| 99 | + static void * |
| 100 | + function(int var1, int var2) |
| 101 | + { |
| 102 | +``` |
| 103 | + |
| 104 | +not: |
| 105 | + |
| 106 | +``` |
| 107 | + static void * |
| 108 | + function(int var1, int var2) { |
| 109 | +``` |
| 110 | + |
| 111 | +## Line Length and Wrap |
| 112 | + |
| 113 | +* Line length should never exceed 79 columns. |
| 114 | + |
| 115 | +* When you have to wrap a long statement, put the operator at the end of the |
| 116 | + line. i.e.: |
| 117 | + |
| 118 | +``` |
| 119 | + if (x && |
| 120 | + y == 10 && |
| 121 | + b) |
| 122 | +``` |
| 123 | + |
| 124 | +Not: |
| 125 | + |
| 126 | +``` |
| 127 | + if (x |
| 128 | + && y == 10 |
| 129 | + && b) |
| 130 | +``` |
| 131 | + |
| 132 | +## Comments |
| 133 | + |
| 134 | +* No C++ style comments allowed. |
| 135 | + |
| 136 | +* When using a single line comment, put it above the line of code that you |
| 137 | +intend to comment, i.e., do: |
| 138 | + |
| 139 | +``` |
| 140 | + /* check variable */ |
| 141 | + if (a) { |
| 142 | +``` |
| 143 | + |
| 144 | +Not: |
| 145 | + |
| 146 | +``` |
| 147 | + if (a) { /* check variable */ |
| 148 | +``` |
| 149 | + |
| 150 | + |
| 151 | +* All public APIs should be commented with Doxygen style comments describing |
| 152 | +purpose, parameters and return values. Private APIs need not be documented. |
| 153 | + |
| 154 | + |
| 155 | +## Header files |
| 156 | + |
| 157 | +* Header files must contain the following structure: |
| 158 | + * Apache License (see above) |
| 159 | + * ```#ifdef``` aliasing, to prevent multiple includes |
| 160 | + * ```#include``` directives for other required header files |
| 161 | + * ```#ifdef __cplusplus``` wrappers to maintain C++ friendly APIs |
| 162 | + * Contents of the header file |
| 163 | + |
| 164 | +* ```#ifdef``` aliasing, shall be in the following format, where |
| 165 | +the package name is "os" and the file name is "callout.h": |
| 166 | + |
| 167 | +```no-highlight |
| 168 | +#ifndef _OS_CALLOUT_H |
| 169 | +#define _OS_CALLOUT_H |
| 170 | +``` |
| 171 | + |
| 172 | +* ```#include``` directives must happen prior to the cplusplus |
| 173 | +wrapper. |
| 174 | + |
| 175 | +* The cplusplus wrapper must have the following format, and precedes |
| 176 | +any contents of the header file: |
| 177 | + |
| 178 | +```no-highlight |
| 179 | +#ifdef __cplusplus |
| 180 | +#extern "C" { |
| 181 | +##endif |
| 182 | +``` |
| 183 | + |
| 184 | +## Naming |
| 185 | + |
| 186 | +* Names of functions, structures and variables must be in all lowercase. |
| 187 | + |
| 188 | +* Names should be as short as possible, but no shorter. |
| 189 | + |
| 190 | +* Globally visible names must be prefixed with the name of the module, |
| 191 | +followed by the '_' character, i.e.: |
| 192 | + |
| 193 | +``` |
| 194 | + os_callout_init(&c) |
| 195 | +``` |
| 196 | + |
| 197 | +Not: |
| 198 | + |
| 199 | +``` |
| 200 | + callout_init(c) |
| 201 | +``` |
| 202 | + |
| 203 | +## Functions |
| 204 | + |
| 205 | +* No spaces after function names when calling a function, i.e, do: |
| 206 | + |
| 207 | +``` |
| 208 | + rc = function(a) |
| 209 | +``` |
| 210 | + |
| 211 | +Not: |
| 212 | + |
| 213 | +``` |
| 214 | + rc = function (a) |
| 215 | +``` |
| 216 | + |
| 217 | + |
| 218 | +* Arguments to function calls should have spaces between the comma, i.e. do: |
| 219 | + |
| 220 | +``` |
| 221 | + rc = function(a, b) |
| 222 | +``` |
| 223 | + |
| 224 | +Not: |
| 225 | + |
| 226 | +``` |
| 227 | + rc = function(a,b) |
| 228 | +``` |
| 229 | + |
| 230 | +* The function type must be on a line by itself preceding the function, i.e. do: |
| 231 | + |
| 232 | +``` |
| 233 | + static void * |
| 234 | + function(int var1, int var2) |
| 235 | + { |
| 236 | +``` |
| 237 | + |
| 238 | +Not: |
| 239 | + |
| 240 | +``` |
| 241 | + static void *function(int var1, int var2) |
| 242 | + { |
| 243 | +``` |
| 244 | + |
| 245 | +* In general, for functions that return values that denote success or error, 0 |
| 246 | +shall be success, and non-zero shall be the failure code. |
| 247 | + |
| 248 | +## Variables and Macros |
| 249 | + |
| 250 | +* Do not use typedefs for structures. This makes it impossible for |
| 251 | +applications to use pointers to those structures opaquely. |
| 252 | + |
| 253 | +* typedef may be used for non-structure types, where it is beneficial to |
| 254 | +hide or alias the underlying type used (e.g. ```os_time_t```.) Indicate |
| 255 | +typedefs by applying the ```_t``` marker to them. |
| 256 | + |
| 257 | +* Place all function-local variable definitions at the top of the function body, before any statements. |
| 258 | + |
| 259 | +## Compiler Directives |
| 260 | + |
| 261 | +* Code must compile cleanly with -Wall enabled. |
| 262 | + |
0 commit comments