C Language Style for Scalability

clarification of ZeroMQ vs. IETF "RFC"s;

added Unix shared libraries, pkg-config declarations, and service management definitions for daemons to the list of things that a project SHOULD deliver;

revised "verbatim" markup in-lined in the text, and fixed a few typos;

requirement by default of asciidoc compatible markup for text files and source comments, unless a different markup is not easily avoidable (this and other aspects of documentation style, format and tooling were since relocated into a separate document: Documentation Recommendation);

added standard text-processing programs among "dependencies" for the projects which aim to deliver rendered end-user documentation formats;

the template README file markup made compatible with asciidoc.

Give project maintainers and contributors a tool for measuring the quality of patches to a project.

Give the code the appearance of a single perfect author writing at one moment in time.

Reduce the number of lines of code and complexity of C projects.

Ensure total consistency of every line of code, across a large number of projects.

Reduce the risk of writing C code by solving common C style problems in a minimal fashion.

Provide a vehicle to collect best practice over time.

The code is easy to read and understand even if you know little or nothing about its specific context.

The code is easy to reuse and remix, in whole or in fragments.

The code is easy to write correctly, and errors are rapidly clear.

If there is no style guide for a project, the maintainers must either rewrite contributions by hand (which costs extra work), or must abandon any attempt to enforce a consistent "voice" across a project (which hurts code quality and reusability). Thus maintainers need a written style guide to which they can point contributors.

If there is no reusable style guide, each project founder will improvise their own ad hoc style. This wastes previous experience, and creates unnecessary work for project founders. It also means each project will end up with a different style.

If a set of projects each have a different style, they cannot share code easily, which damages the economics of remixing. The more projects that use a single style, the lower the cost of code reuse. This is especially important in open source but also applies to projects built internally in an organization.

With no vehicle for collecting and sharing best practices in C programming, most projects will have mediocre structuring and style, leading to unnecessary complexity, excess lines of code, accumulation of unused code, and other quality problems.

When project founders create a new project without help, they often make mistakes such as forgetting to define a license for their code. This can create legal problems.

Names SHALL be short words that are simple, clear, and obvious to the reader.

Names SHALL be used consistently for any given semantics.

Names SHOULD NOT be invented words or acronyms.

Names MAY be abbreviations if used widely.

Names SHALL NOT be reserved C or C++ keywords.

A project short name used in paths and URLs that identify the project. This would be used for instance in the GitHub project name. In this Specification we will use myproject as the example.

A project prefix used for project files, output libraries, and method names. This would be used for instance in the library produced for the project. The prefix MAY be an acronym. In this Specification we will use myp as the example.

A README file that refers to this Specification and provides other necessary information about the project.

A license file (e.g., COPYING or LICENSE) that specifies the terms of distribution for the project.

An include directory for all header files.

A src directory for all library source files.

The public header file (include/myproject.h).

Scripts and makefiles to build and test the project on at least one platform.

An AUTHORS file listing all contributors to the project.

A doc directory containing documentation.

The internal header file (src/myp_classes.h).

The project header files and all class header files that form part of the public API.

The project library, named with the project prefix (libmyp.a and/or libmyp.so(.*) on POSIX platforms and libmyp.pc declarations for the pkg-config, and myp.dll on Windows).

Command-line tools, if present.

Distribution-dependent service files for programs intended to run as daemons (e.g. classic init-scripts, systemd units, Solaris SMF manifests).

To create backwards compatibility with older code.

To improve portability by e.g., mapping non-portable system calls into more portable ones.

To create precise, small macros with high usability.

A header file: include/myp_myclass.h

A source file: src/myp_myclass.c

The name of the class or file and its purpose

The copyright statement for the class

The name of the project and a URL if relevant

The summary license statement

Stateful classes, where the class provides methods working on instances, which are like "objects" in an object-oriented language.

Stateless classes, where the class provides methods that work purely on data provided by the caller or system.

A constructor method myp_myclass_new ()

A destructor method myp_myclass_destroy ()

A self-test method myp_myclass_test ()

A duplicator method myp_myclass_dup ()

A set of list navigation methods myp_myclass_first () and myp_myclass_next ().

Print methods myp_myclass_print () and myp_myclass_fprint ().

A self-test method myp_myclass_test ().

The file header

An outer #ifndef that makes it safe to include the header file multiple times

Calling conventions for C++

A forward reference to the class type, for stateful classes

Prototypes for the class methods

The class structure, for stateful classes. This structure SHALL be opaque and known only to code in the class source file.

The class methods, in the same order as defined in the class header: constructor, destructor, other methods, and finally self test.

Any static functions used in the class methods.

Any global or static variables needed.

The self test method SHALL be a primary source of example code for users of the class.

The self test method SHOULD cover every other method in the class.

The constructor SHALL initialize all properties in new class instances. Properties SHALL either get a suitable initial value, or be set to zero. Very large properties MAY exceptionally be left uninitialized for performance reasons; such behavior MUST be explicitly noted in the constructor body.

Any properties that are dynamically allocated SHOULD be allocated in the constructor but MAY be left as null.

The constructor MAY take one or more arguments, which SHALL correspond to properties to be initialized.

The constructor SHALL return either a new instance reference, or null, if construction failed.

The destructor SHALL null-ify the provided instance reference.

The destructor SHALL be idempotent, i.e. it can be called safely on the same instance reference more than once.

The destructor SHALL safely free properties and child class instances that are not null.

The duplicator SHALL return either a new instance reference, or null if construction failed, in the same manner as the constructor.

The duplicator SHALL accept a null instance reference, and then return null.

A duplicated instance SHALL be entirely independent of the original instance (i.e. all properties SHALL also be duplicated).

The navigation methods SHALL return null to indicate "no more items".

The navigation methods SHALL be idempotent, and specifically, calling myp_myclass_next () when at the end of the list SHALL return null each time.

The class MAY offer myp_myclass_last () and myp_myclass_prev () methods.

The class MAY offer myp_myclass_size () which returns the list size.

If the class offers methods to create list items, these SHALL be called myp_myclass_append () (to add to the end of the list) and myp_myclass_insert () (to add to the start of the list).

If the class offers a method to remove a list item, this SHALL be called myp_myclass_delete (); it SHALL take the item reference as argument, and it SHALL delete the first matching item in the list, if any.

If the class maintains multiple lists, it SHALL create unique method names for each list by adding a list name, e.g., myp_myclass_myitem_first ().

Properties exposed by accessor methods MAY not actually exist as such in the instance; they may be calculated rather than simply copied to/from the instance structure.

The first argument to the method SHALL be the instance reference.

Other arguments may follow.

Returning nothing, if no return value is expected.

Returning a property value, on an accessor method.

Returning an object instance, on a constructor or duplicator.

Returning a child value, on a list navigation method.

Returning zero on success, -1 on failure.

Returning a freshly-allocated string.

All methods SHALL be thread safe.

Class instances SHOULD NOT generally be thread safe; a class instance will be owned by a single calling thread.

In exceptional cases class instances MAY be made thread safe by the addition of mutexes or locks inside methods.

When a class instance has been destroyed, all heap memory it used MUST be freed. Classes SHALL NOT leak memory under any conditions except during abnormal termination (e.g., on a failed assertion).

Non-atomic properties SHOULD be re-allocated (i.e., freed and allocated) in accessor functions that modify them, as needed.

The instance structure MAY use char[] arrays instead of heap allocated char* pointers.

When freeing a non-atomic property outside the destructor, a method MUST set the property to null if it does not allocate a new value immediately.

Variables and functions SHALL use lower-case names.

Where necessary, underlines SHALL be used to separate parts of a name.

Variable names like i and temp that carry no information SHALL NOT be used.

In-line comments SHALL use the C++ // style.

Multi-line comments MAY use the C /* ... */ style or MAY use the C++ // style.

When possible in-line comments shall start at column 33.

In in-line comments, the // or /* shall be followed by two spaces.

Every function shall have a multi-line comment header that briefly explains its purpose.

Method comment headers SHALL be preceded by a line of hyphens ending at column 78.

Suitably-marked-up comments before a function MAY be used as source material for reference documentation.

Every property in a class structure SHALL have a 1-line in-line comment that describes its purpose.

Comments SHALL NOT be used to compensate for illegible code.

Code that cannot be reasonably read and understood by the casual reader SHOULD be rewritten, not annotated.

Properties and functions whose semantics are not clear from their names SHOULD be renamed, not annotated.

After the closing bracket of a function body and before the comment header for a function.

To break up blocks of code that exceed 6-8 lines.

After assertions at the start of a class body.

After an if statement with a single-statement block.

After multi-line case blocks inside a switch statement.

After multi-line comment blocks.

After the closing bracket of a conditional block.

To separate individual lines of code that could better be grouped together.

Assertions SHALL be used for their documentary value, for example to warn the reader, "this argument SHALL NOT be null".

Assertions on arguments SHALL come at the start of the class body and SHALL follow the order of the arguments.

Assertions MAY be used on return values from function calls if such failures cannot safely be handled by the code.

Assertions MAY be used on internal state (e.g., instance properties) to assert a mandatory condition for continuing.

Assertions SHALL NOT be used to trap errors on external conditions, e.g., bad user input, invalid protocol messages, etc.

Assertions SHOULD be used to trap errors on internal APIs, e.g. invalid messages sent from one thread to another.

Assertions SHALL NOT have side-effects since the entire statement may be removed by an optimizing compiler.

The recommended pattern for an open-ended loop is while (true) {}, with break statements as needed to exit the loop.

The recommended pattern for array iteration is:

The recommended pattern for list iteration is:

A class SHALL be either "portable" or "native".

A portable class SHALL NOT use the preprocessor to compile differently on different systems.

A native class SHALL export a properly abstracted API that hides system differences, and SHALL use the preprocessor to compile differently on different systems.

A native class SHALL use the preprocessor macros defined in czmq_prelude.h, and specifically the WINDOWS, UNIX, and __UTYPE_ABC macros.

A native class SHALL NOT use preprocessor macros supplied by any specific build system. If the CZMQ-supplied macros are not sufficient these can be improved and extended.

The project architect SHOULD aim to fully separate portable and native classes, so that application developers see and write only portable classes.

bool, true, false: Boolean data type and constants.

byte, dbyte, qbyte: unsigned 1-, 2-, and 4-octet integers.

uint, ulong: unsigned integers and longs.

int32_t, int64_t: signed 32-bit and 64-bit integers.

uint32_t, uint64_t: unsigned 32-bit and 64-bit integers.

streq (s1, s2): preferred over strcmp (s1, s2) == 0.

strneq (s1, s2): preferred over strcmp (s1, s2) != 0.

randof (number): return random integer in range 0 .. number - 1.

srandom: typically used like this: srandom ((unsigned) time (NULL));

inline, snprintf, vsnprintf: Windows uses non-POSIX variants with underscores.

Assigning a void pointer to a typed pointer without a cast. Always cast a void * before assigning it to a typed pointer.

Failing to return a value in a non-void function. Always end a non-void function with a return statement.

The code generator SHOULD be GSL, from https://github.com/imatix/gsl.

All code generation scripts SHALL be in the project src subdirectory.

All model data (XML files) SHALL be in the project src directory.

If only parts of a class are generated, these parts SHALL have the extension .inc and SHALL be generated into the project src directory, and SHALL be included in the class source file using an #include statement.

Code generation SHALL be done as a manual step. For example, make code. All generated code SHALL be committed into the project as for hand-written files.

Code generation SHALL be fully idempotent, that is, generated code SHALL NOT contain any date or time stamps.

Code generation SHALL be treated as a form of dangerous abstraction that creates significant barriers to readers. A good rule of thumb is that for code generation to be profitable, it should reduce the lines of code written by hand by 80-90%.

Generated code SHALL contain a warning of this form at the start: GENERATED SOURCE CODE, DO NOT EDIT.

Generated code SHALL otherwise conform to this Specification so that it is indistinguishable from hand-written code.

Code SHALL NOT share state between threads except in exceptional and limited cases. Threads SHALL communicate by passing 0MQ messages.

Classes SHALL not use static variables since this is not re-entrant, thus not thread safe.

Class instances SHALL NOT be passed between threads except in "hand-off" cases.

Code SHOULD NOT use mutexes, locks, or other mechanisms to share state between threads.

Code MUST NOT use non-thread safe system calls such as basename ().

Code MUST always truncate over-long data.

Code MUST NOT use unsafe system calls such as gets ().

The heavy reliance on heap memory means that CLASS applications are vulnerable to denial-of-service attacks. Applications can mitigate this risk by enforcing limits on the number of class instances they create.

The heavy reliance on heap memory makes CLASS unsuitable for embedded systems where all memory use must be static.

In most CLASS applications it is difficult to handle an "out of memory" error in any way except to abort.