codingStyle

/**
 * Description of the coding style for the source files.
 *
 * @file        codingStyle
 * @ingroup     codingStyle
 * @author      name
 * @copyright   2020 name
 *
 * Licensed 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.
 */

#ifndef XYZ_H
#define XYZ_H

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @defgroup codingStyle Description of coding style
 * @ingroup parentGroup
 * @{
 *
 * Contents of this file should be the base for .h source file, except function
 * body at the end.
 *
 * ###Style
 *  - Style is based on https://github.com/MaJerle/c-code-style
 *  - Indent size is 4 spaces, no tabs.
 *  - Line width is 80 characters.
 *  - Some (old) code may not be formatted according to the rules. Try to avoid
 *    unnecessary changes based on individual taste.
 *
 * ###Doxygen
 * Documentation is generated by doxygen.
 * Doxygen comment starts with /**. /**< is used after member.
 * Documentation is usually in header.
 * Doxygen settings:
 *  - JAVADOC_AUTOBRIEF = YES.
 *  - See doxyfile for other settings.
 *
 * Doxygen specifics: If description of the structure member is one sentence
 * only, don't use period after the sentence.
 */

/**
 * Brief description of the object ends at this dot. Details follow
 * here.
 */
typedef struct {
    int8_t member1;   /**< Short description of the member 1 */
    uint16_t member2; /**< Note the '/**<' sequence after the member 2 */
    /** Long description of the variable stringMember. More description. */
    char_t stringMember[5];
} object1_t;

/**
 * Function example 1.
 *
 * This is global function. Local functions (and variables) used inside one file
 * are declared as static and not documented by Doxygen.
 *
 * @param thisObj Pointer to object. Function operates on this object (not on
 * global variables).
 * @param argument_2 Description of the argument.
 * @param argument_2 Description of the argument.
 * @param argument_4 Description of the argument.
 *
 * @return Some value.
 */
int32_t
foo1(object1_t* thisObj, int32_t argument_2, uint16_t argument_3, float32_t argument_4, bool_t argument_5,
     int32_t argument_6) {
    /* Comment */

    /* Multiline
     * comment.
     */

    /* All if and else statement must have use { } around their bodies
     * (MISRA C 2004 rule 14.9)
     */
    if (xy == yz) { /* Comment. '//' comments are not allowed */
        a = b;
    } else if (xy < yz) {
        a = c;
    } else {
        /* To stay compliant with MISRA C 2004 14.10
         * all else if statements need a final else even if empty
         */
    }

    /* Assignment operators shall not be used in expressions which return
     * boolean values (MISRA C 2004 rule 13.1)
     * This is true for: 'if' and 'while' statements.
     * For instance:
     */
    if (xy = yz) {}
    while (xy = yz) {}

    switch (zx) {
        case 1:
            a = b;
            break default :
                /* To stay compliant with MISRA C 2004 15.3
                 * the default case must be present */
                break;
    }
}

/* MISRA C 2004 Rule E14.4.3
 * There should be no more than one break or goto statement used to terminate
 * any iteration statement.
 */

/* MISRA C 2004 Rule 14.5
 * The continue statement shall not be used.
 */

/* More about MISRA C
 * https://www.ibm.com/docs/en/devops-test-embedded/9.0.0?topic=review-code-misra-2004-rules
 */

/** @} */

#ifdef __cplusplus
}
#endif /*__cplusplus */

#endif /* XYZ_H */