Guide for the coding style used in this SDK.
The goal of this style guide is to encourage a readable and consistent coding style across the entire SDK.
The coding style used in this SDK.
The coding style aims to produce code that is readable and easy to debug. An example is provided in Example File.
General guidelines for library style.
/
*
and */
should be used to start and end comments.goto
is discouraged.static
functions must have a declaration at the top of the file and be implemented before any application-facing functions.Guidelines for variable types.
bool
and types required by third-party APIs.int32_t
or uint32_t
.size_t
.bool
macros for use with C89 compilers.An example file that follows the coding style rules.
See Naming for how to name the functions, variables, and macros.
Naming convention used in this SDK.
The naming convention aims to differentiate this SDK's files, variables, and functions to avoid name collisions. In general:
core_mqtt_serializer.c
identifies a file as part of the general MQTT library. MQTT_Connect
identifies a public-facing function of the general MQTT library.Naming convention for constants set using preprocessor #define
and enum values.
This table contains the formats for the names of the most common SDK defined constant and enum values. It is not intended to be comprehensive. Bold text indicates a variable but required part of the defined constant and enum value's name.
Format | Applies to | Example |
---|---|---|
LibraryDescription | Defined constants and enum values in application-facing library header files | MQTTSuccess (core_mqtt_lightweight.h) |
LIBRARY_DESCRIPTION | Defined constants and enum values in demos and tests | MQTT_EXAMPLE_TOPIC |
DESCRIPTION | Internal constants and enum values No AWS_ prefix for internal names in AWS-specific libraries | ROOT_CA_CERT_PATH |
Naming convention for files.
This table contains the formats for the names of the most common SDK files. It is not intended to be comprehensive. Bold text indicates a variable but required part of the file's name.
Format | Applies to | Example |
---|---|---|
library_ description.extension | General library file | core_mqtt_serializer.c |
library_internal.h | Internal library header | core_mqtt_internal.h |
library_demo_ description.c | Library demo source | mqtt_demo_plaintext.c |
library_description_utest.c library_description _system_test.c | Library test source | core_mqtt_utest.c mqtt_system_test.c |
File names contain only lowercase letters and underscores. All file names should be named according to their purpose. For example:
core_mqtt_state.c
: A file in the MQTT library that handles state of MQTT PUBLISH packet deliveries.mqtt_demo_plaintext.c
: A file in the demos for the MQTT library that communicates over a plaintext channel.core_mqtt_utest.c
: A file in the Tests for the MQTT library. Since the tests currently only run on POSIX systems, test file names do not use the _posix
suffix.Library file names should use one or two words to describe the functions implemented in that file. For example:
core_mqtt_serializer.c
: Implements the MQTT library's packet serialization and deserialization functions.clock_posix.c
: Implements the platform clock component for POSIX systems.Declarations of internal functions, structures, macros, etc. of a library should be placed in a header file with an _internal
suffix. The _internal
header file should go in the source/include/private
directory. For example:
core_mqtt_internal.h
: Declares the MQTT library's internal functions, structures, macros, etc.File names for demos should begin with library_demo_
. Unit tests must start with library_
and end with _utest
. System tests must start with library_
and end with _system_test
. The names should then specify the library being demoed or tested. For example, the files names of the MQTT library's demos start with mqtt_demo_
. Additionally, test file names should describe what tests are implemented in the file, such as mqtt_demo_mutual_auth.c
for a file containing a demo that mutually authenticates over TLS with an MQTT broker.
Naming convention of functions and function-like macros.
This table contains the formats for the names of the most common SDK functions. It is not intended to be comprehensive. Bold text indicates a variable but required part of the function's name.
Format | Applies to | Example |
---|---|---|
Library_ Description | Externally-visible library function | MQTT_Publish |
description | static function (never uses Aws prefix) | sendPublish eventCallback |
test_ Library_ accessedFunction_Description | Test access function | test_MQTT_ProcessLoop_Timer_Overflow |
Externally visible (i.e. not static
) functions are UpperCamelCased. Function names should then specify their library name, followed by an underscore, followed by a brief description of what the function does. For example:
MQTT_SerializePublish
: This function is part of the public MQTT API. It serializes an MQTT PUBLISH packet into a buffer.Functions not visible outside their source file (i.e. static
functions) have names that are lowerCamelCased. These function names do not contain the library name or Aws
. For example:
receiveSingleIteration
: A static
function in core_mqtt.c
.Naming conventions of library typedef
types.
This table contains the formats for the names of the most common SDK types. It is not intended to be comprehensive. Bold text indicates a variable but required part of the type's name.
Format | Applies to | Example |
---|---|---|
LibraryDescription_t | General types in application-facing library header files | MQTTStatus_t (core_mqtt.h) |
Types intended for use in applications are UpperCamelCased. The names end with _t
. Parameter structures should indicate their associated function: for example, MQTTPublishInfo_t
is passed as a parameter to MQTT_Publish
.
Types intended for internal library use defined in a header file are lowerCamelCased. The names must start with the library name and end with _t
. Internal types defined in a library source file must end with _t
and not include the library name.
struct
typedefs should always be named along with the typedef
. The struct name should be identical to the typedef
name, but without the _t
suffix. For example:
A struct
may contain union
members, but its usage must be documented as it violates MISRA rule 19.2.
Naming conventions of variables.
This table contains the formats for the names of the most common SDK variables. It is not intended to be comprehensive. Bold text indicates a variable but required part of the variable's name.
Format | Applies to | Example |
---|---|---|
variableDescription | General local variable | startTime |
p VariableDescription | Variable pointers and arrays (including strings) | pSubscriptionList |
Local variable names are lowerCamelCased and consist only of a description of the variable. Names like i
or j
are acceptable for loop counters, but all other variables should have a descriptive name.
Global variables that are static
consist of only the description in lowerCamelCase. Global variables that are not static consist of the library name and the description in UpperCamelCase.
All pointers, arrays, and strings (both global and local) start with p
.