Page 217 - The Art of Designing Embedded Systems

204 THE ART OF DESIGNING EMBEDDED SYSTEMS

future version of yourself. Just as standard English grammar and spelling
make prose readable, standardized coding conventions ease readability of
one’s firmware.
Part of every code review is to insure the reviewed modules and func-
tions meet the requirements of the Standard. Code that does not meet this
Standard will be rejected.
We recognize that no Standard can cover every eventuality. There
may be times where it makes sense to take exception to one or more of the
requirements incorporated in this document. Every exception must meet
the following requirements:

Clear Reasons-Before making an exception to the Standard, the
programmer(s) will clearly spell out and understand the reasons in-
volved, and will communicate these reasons to the project man-
ager. The reasons must involve clear benefit to the project and/or
company; stylistic motivations, or programmer preferences and
idiosyncrasies are not adequate reasons for making an exception.
Approval-The project manager will approve all exceptions made.
Documentation-The effected module or function will have the
exception clearly documented in the comments, so during code
reviews and later maintenance, the current and future technical
staff understand the reasons for the exception, and the nature of the
exception.

Projects
Directory Structure
To simplify use of a version control system, and to deal with unex-
pected programmer departures and sicknesses, every programmer involved
with each project will maintain identical directory structures for the source
code associated with the project.
The general “root” directory for a project takes the form:
/proj ec ts/proj ec t-namehorn-name
where
“/projects” is the root of all firmware developed by the company.
By keeping all projects under one general directory, version control
and backup are simplified and reduce the size of the computer’s
root directory.
“/project-name’’ is the formal name of the project under develop-
ment.