CODING_STANDARDS.md

# Coding Style for Apache Mynewt Core

This document is meant to define the coding style for Apache Mynewt, and 
all subprojects of Apache Mynewt.  This covers C and Assembly coding 
conventions, *only*.  Other languages (such as Go), have their own 
coding conventions.

## Headers

* All files that are newly written, should have the Apache License clause
at the top of them.

* For files that are copied from another source, but contain an Apache 
compatible license, the original license header shall be maintained.

* For more information on applying the Apache license, the definitive 
source is here: http://www.apache.org/dev/apply-license.html

* The Apache License clause for the top of files is as follows:

```no-highlight
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 * 
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
```

## Checking coding-style locally

To maintain code quality and consistency across the project, all contributors
**should** verify that their committed changes conform to the project's coding style
before pushing to the remote repository.

We strongly recommend running git-clang-format locally to check your committed changes.
This helps catch formatting issues early, avoiding CI failures and reducing review delays.

> **Tip:** Before pushing your commits, run this command to see any formatting issues that need fixing:
>```sh
>git-clang-format $(git merge-base upstream/master HEAD) HEAD --diff
>```

**Note**: If clang-format produces incorrect or undesirable results (e.g., mangled macros or formatting bugs),
you may temporarily bypass the formatting check by applying the skip-style-check label to the pull request.
Use this only when necessary and explain the reason in the PR description.

## Whitespace and Braces

* Code must be indented to 4 spaces, tabs should not be used.

* Do not add whitespace at the end of a line.

* Put space after keywords (for, if, return, switch, while).

* for, else, if, while statements must have braces around their 
code blocks, i.e., do: 

```
    if (x) {
        assert(0);
    } else {
        assert(0);
    }
```

Not: 

```
    if (x) 
        assert(0);
    else
        assert(0);
```

* Braces for statements must be on the same line as the statement.  Good:

```
    for (i = 0; i < 10; i++) {
        if (i == 5) {
            break;
        } else {
            continue;
        }
    }
```

Not:

```
    for (i = 0; i < 10; i++) 
    { <-- brace must be on same line as for
        if (i == 5) {
            break;
        } <-- no new line between else
        else {
            continue;
        }
    }
```

* After a function declaration, the braces should be on a newline, i.e. do:

```
    static void *
    function(int var1, int var2)
    {
```

not: 

```
    static void *
    function(int var1, int var2) {
```

## Line Length and Wrap

* Line length should never exceed 79 columns.

* When you have to wrap a long statement, put the operator at the end of the 
  line.  i.e.:

```
    if (x &&
        y == 10 &&
        b)
```

Not:

```
    if (x
        && y == 10
        && b)
```

## Comments

* No C++ style comments allowed.

* When using a single line comment, put it above the line of code that you 
intend to comment, i.e., do:

```
    /* check variable */
    if (a) {
```

Not:

```
    if (a) { /* check variable */
```


* All public APIs should be commented with Doxygen style comments describing 
purpose, parameters and return values.  Private APIs need not be documented.


## Header files

* Header files must contain the following structure:
    * Apache License (see above)
    * ```#ifdef``` aliasing, to prevent multiple includes
    * ```#include``` directives for other required header files
    * ```#ifdef __cplusplus``` wrappers to maintain C++ friendly APIs
    * Contents of the header file

* ```#ifdef``` aliasing, shall be in the following format, where
the package name is "os" and the file name is "callout.h": 

```no-highlight
#ifndef _OS_CALLOUT_H
#define _OS_CALLOUT_H
```

* ```#include``` directives must happen prior to the cplusplus 
wrapper.

* The cplusplus wrapper must have the following format, and precedes
any contents of the header file:

```no-highlight
#ifdef __cplusplus
#extern "C" {
##endif
```

## Naming

* Names of functions, structures and variables must be in all lowercase.  

* Names should be as short as possible, but no shorter.  

* Globally visible names must be prefixed with the name of the module, 
followed by the '_' character, i.e.: 

```
    os_callout_init(&c)
```

Not:

```
    callout_init(c)
```

## Functions

* No spaces after function names when calling a function, i.e, do:

```
    rc = function(a)
```

Not: 

```
    rc = function (a)
```


* Arguments to function calls should have spaces between the comma, i.e. do:

```
    rc = function(a, b)
```

Not: 

```
    rc = function(a,b)
```

* The function type must be on a line by itself preceding the function, i.e. do: 

```
    static void *
    function(int var1, int var2)
    {
```

Not: 

```
    static void *function(int var1, int var2)
    {
```

* In general, for functions that return values that denote success or error, 0
shall be success, and non-zero shall be the failure code.

## Variables and Macros

* Do not use typedefs for structures.  This makes it impossible for 
applications to use pointers to those structures opaquely.  

* typedef may be used for non-structure types, where it is beneficial to 
hide or alias the underlying type used (e.g. ```os_time_t```.)   Indicate
typedefs by applying the ```_t``` marker to them.

* Place all function-local variable definitions at the top of the function body, before any statements.

## Compiler Directives

* Code must compile cleanly with -Wall enabled.