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