Lang C Code Writing

C Code Writing — Automotive Embedded

A senior embedded engineer's complete mental checklist for writing and reviewing production-quality C code on Android Automotive / Linux / QNX platforms. Standards baseline: C99 / C11 + MISRA C:2012 (mandatory rules).

When to Use This Skill

• Writing a new .c / .h module from scratch.
• Reviewing a pull request / Gerrit patch that touches C files.
• Refactoring legacy C code to meet MISRA or AUTOSAR quality gates.
• Resolving Coverity or static-analysis findings in C files.
• Generating Doxygen-ready file/function headers.

Prerequisites

• Target standard confirmed: C99 or C11 (default: C11).
• Safety classification known: QM / ASIL-A…D (affects required rule set).
• Compiler and platform known (GCC cross-arm, QCC for QNX, etc.).
• <stdint.h> and <stdbool.h> available on the target toolchain.

Step-by-Step Workflow

Step 1 — File & Header Structure

Every .h file must have an include guard and a Doxygen file block:

/**
 * @file   sensor_driver.h
 * @brief  Public interface for the temperature sensor driver.
 *
 * @details
 *   Provides initialise / read / deinitialise operations for the NTC
 *   sensor attached to ADC channel 3.  Thread-safe when used with a
 *   single reader and single writer; concurrent writers require external
 *   locking.
 *
 * @author  <author>
 * @date    2026-03-14
 */

#ifndef SENSOR_DRIVER_H
#define SENSOR_DRIVER_H

#include <stdint.h>
#include <stdbool.h>

/* ... declarations ... */

#endif /* SENSOR_DRIVER_H */

• One concept per header — do not bundle unrelated APIs.
• No function definitions in headers (inline allowed only for trivial accessors).
• System includes (< >) before project includes (" "), alphabetically sorted.

Step 2 — Type Selection

MISRA C:2012 Rule 10.1 — 10.4: Operands must have appropriate essential type; no implicit conversions between signed/unsigned.

Step 3 — Function Design

/**
 * @brief  Read the current temperature from the NTC sensor.
 *
 * @param[out] pTemperature_degC  Pointer to store the result in °C.
 *                                Must not be NULL.
 * @return ::SensorError_t  SENSOR_OK on success, error code otherwise.
 *
 * @pre   Sensor_Init() must have been called successfully.
 * @post  *pTemperature_degC is valid only when SENSOR_OK is returned.
 * @thread_safety  Safe for single-reader, single-writer; see file header.
 */
SensorError_t Sensor_ReadTemperature(int16_t * const pTemperature_degC);

Rules:

• One responsibility per function; aim for < 50 executable lines.
• Every parameter that is a pointer: annotate [in], [out], or [in,out].
• Output pointers must be checked for NULL at function entry:

  if (pTemperature_degC == NULL) { return SENSOR_ERR_NULL_PTR; }
  

• No side effects via global state without explicit documentation.
• Naming: Module_ActionNoun() — Sensor_ReadTemperature, Can_SendFrame.

Step 4 — Error Handling

Define a module-specific error enum — never return raw integers:

/** @brief Return codes for the Sensor module. */
typedef enum
{
    SENSOR_OK            = 0,   /**< Operation completed successfully. */
    SENSOR_ERR_NULL_PTR  = 1,   /**< Caller passed a NULL pointer.    */
    SENSOR_ERR_NOT_INIT  = 2,   /**< Module not initialised.          */
    SENSOR_ERR_TIMEOUT   = 3,   /**< Hardware did not respond in time. */
    SENSOR_ERR_HW_FAULT  = 4    /**< Unrecoverable hardware error.    */
} SensorError_t;

Pattern at call sites — always check return values:

SensorError_t err = Sensor_ReadTemperature(&temp);
if (err != SENSOR_OK)
{
    Log_Error("Sensor_ReadTemperature failed: %d", (int32_t)err);
    return MY_MODULE_ERR_SENSOR;   /* propagate; never silently ignore */
}

MISRA C:2012 Rule 17.7: The return value of a non-void function shall be used.

Step 5 — Memory & Resource Management

/* GOOD — static allocation with explicit size constant */
#define SENSOR_BUFFER_SIZE  (64U)
static uint8_t s_rxBuffer[SENSOR_BUFFER_SIZE] = {0U};

/* BAD — VLA, forbidden by MISRA C:2012 Rule 18.8 */
uint8_t buffer[n];   /* n is a runtime variable */

Step 6 — Null & Bounds Safety

/* Guard every pointer before use */
void Process_Frame(const uint8_t * const pData, uint16_t length)
{
    if ((pData == NULL) || (length == 0U))
    {
        return;   /* or return error code */
    }

    for (uint16_t i = 0U; i < length; i++)
    {
        /* safe: i is bounds-checked */
        DoWork(pData[i]);
    }
}

• No pointer arithmetic outside a dedicated, named utility function.
• sizeof on pointer vs. array: always use the array name, not a pointer to it.
• String operations: prefer strncpy / snprintf with explicit size; never strcpy / sprintf.

Step 7 — Constants & Magic Numbers

/* GOOD */
#define ADC_VREF_MV         (3300U)   /**< ADC reference voltage in mV. */
static const uint8_t  K_MAX_RETRIES = 3U;
static const uint32_t K_TIMEOUT_MS  = 100UL;

/* BAD */
if (retries > 3)      /* magic number */
if (voltage < 3300)   /* undocumented constant */

• #define constants: ALL_CAPS, bracketed, with U/UL suffix for unsigned.
• static const preferred over #define when type matters.
• enum for grouped symbolic values (state-machine states, event IDs).

Step 8 — MISRA C:2012 Priority Checklist

Work through this before submitting to Coverity / static-analysis:

For known required deviations, add a deviation comment:

/* MISRA C:2012 Rule 11.3 deviation — required for HW register map cast,
   reviewed and approved in safety analysis SA-2024-007. */
pReg = (volatile Reg_t *)(uint32_t)BASE_ADDR;  /* NOLINT */

Step 9 — Thread Safety & Concurrency

/* Document assumptions at the top of the .c file */
/**
 * @section thread_safety Thread Safety
 *   - Sensor_Init() / Sensor_Deinit(): must be called from a single
 *     initialisation thread only.
 *   - Sensor_ReadTemperature(): safe for concurrent readers; internal
 *     state is read-only after init.
 *   - Sensor_Calibrate(): NOT thread-safe; caller must hold s_moduleMutex.
 */

• Shared mutable state → protect with pthread_mutex_t or platform equivalent.
• Prefer message passing / queue over shared memory in RTOS contexts (QNX pulses).
• volatile for memory-mapped registers and ISR-shared flags; it is not a synchronisation primitive.

Step 10 — Review Checklist

• Include guard present and unique (MODULE_FILE_H)
• Doxygen @file block in every .h; @brief on every public symbol
• All parameters annotated [in] / [out] / [in,out]
• Every pointer checked for NULL at function entry
• No malloc/free in ISR or ASIL paths (or deviation documented)
• No magic numbers — all literals named
• All return values checked
• No VLAs (uint8_t buf[n] where n is runtime)
• No implicit integer conversions across sign boundary
• File-scope variables are static unless deliberately exported
• No goto, no dead code, no commented-out blocks
• Thread-safety assumptions documented
• MISRA deviations commented with justification and deviation ID

Pre-Commit Checklist

• Include guard present and unique (MODULE_FILE_H)
• Doxygen @file in every .h; @brief on every public symbol; all params annotated [in]/[out]
• Every pointer checked for NULL at function entry
• All return values checked — no silently ignored error codes
• No malloc/free in ISR or ASIL paths (or deviation documented)
• No magic numbers — all literals named with #define or enum
• No implicit integer conversions across sign boundary (-Wsign-compare clean)
• No VLAs (uint8_t buf[n] where n is runtime-determined)
• File-scope variables declared static unless deliberately exported
• No goto, no unreachable code, no commented-out blocks
• Thread-safety assumptions documented in Doxygen
• MISRA deviations annotated with justification comment and deviation ID
• Compiles with 0 warnings under -Wall -Wextra -Wpedantic

Examples

Good — Defensive function with error enum

/* See examples/good_sensor_read.c */
SensorError_t Sensor_ReadTemperature(int16_t * const pTemperature_degC)
{
    if (pTemperature_degC == NULL)
    {
        return SENSOR_ERR_NULL_PTR;
    }

    if (!s_isInitialised)
    {
        return SENSOR_ERR_NOT_INIT;
    }

    uint16_t rawAdc = Adc_ReadChannel(ADC_CHANNEL_NTC);
    *pTemperature_degC = Convert_AdcToTemp(rawAdc);

    return SENSOR_OK;
}

Bad — Raw int return, unchecked pointer, magic number

/* BAD: multiple violations */
int readTemp(int16_t *t)          /* no fixed-width type on return */
{
    *t = adc_read(3) * 100 / 4096; /* NULL not checked; magic numbers */
    return 0;                       /* return value meaning not documented */
}

Troubleshooting

References

• MISRA C:2012 — MISRA Consortium
• Coverity Static Analysis
• AUTOSAR C++14 Guidelines