Some people claim that spacing is not important and that spacing rules in a coding style are burdensome and bogus. Review the following example to see why spacing is important, especially in C:
int i;main(){for(;i["]<i;++i){--i;}"];read('-'-'-',i+++"hello,
world!\n",'/'/'/'));}read(j,i,p){write(j/p+p,i---j,i/i);}Dishonorable mention, Obfuscated C Code Contest, 1984.
Author requested anonymity.
Use blank lines to
- make code more readable
- group logically related sections together.
This requirement does not include for loops, where the initial, conditional,
and loop statements may go on a single line.
The conditional and code always go on a separate line.
It should be:
if (MyVar != 0) {
MyTrueCode ();
}5.2.1.3 An open brace '{' goes on the same line as the closing parenthesis ')' of simple predicate expressions
This requirement includes functions and data. A simple predicate expression is one containing zero or one operator which fits on the same line as the keyword.
while (MyVar != 0) {
Indent the brace to match the first line of the construct.
while (MyVar != 0) {
MyTrueCode ();
}} else {
} else if (foo) {
} while (bar);Predicate expressions containing multiple operators with sub-expressions joined
by && or || must have each sub-expression on a separate line. The opening brace,
'{' of the body shall be on a line by itself and aligned in the starting
column of the associated keyword.
while ( ( Code == MEETS_STANDARD)
&& ( Code == FUNCTIONAL))
{
ShipIt();
}This space makes both operands much easier to read.
if (MyVar != 0) {
MyTrueCode ();
}If ((--MyInteger) > 0) {
5.2.2.4 Subsequent lines of multi-line function calls should line up two spaces from the beginning of the function name
If a function call or function like macro invocation is broken up into multiple lines, then:
- One argument per line, including the first argument on its own line.
- Indent each argument 2 spaces from the start of the function name. If a function is called through a structure or union member, of type pointer-to-function, then indent each argument 2 spaces from the start of the member name.
- Align the close parenthesis with the start of the last argument
CopyMem (
Destination,
Source,
SIZE_4KB
);
Status = gBS->AllocatePool (
EfiBootServicesData,
sizeof (DRIVER_NAME_INSTANCE),
&PrivateData
);
DEBUG ((
DEBUG_INFO,
"The addresses of the 4 buffers are %p, %p, %p, and %p\n",
Buffer1,
Buffer2,
Buffer3,
Buffer4
));This punctuation is not necessary if no code or comments follow the comma or semicolon.
EfiLibAllocateCopyPool (Size, DevicePath);
for (Size = 0; FileName[Size] != 0; Size++) {...The only exception is macro definitions.
if (...
while (...
EfiLibAllocateCopyPool (...if () {
while () {
Data.Index
Pointer->Index = *Ptr;Array[(Max + Min) / 2]
5.2.2.10 Use extra parentheses rather than depending on in-depth knowledge of the order of precedence of C
(The order of precedence should be the compiler's job, not yours.)
Consider the following expression:
8 | 8 == 8
On first glance, one might think that the expression would evaluate to TRUE.
This is not the case. The bitwise OR operator, '|', has lower precedence than
the equality operator, '=='. This results in the expression being evaluated as
if one had entered:
8 | ( 8 == 8 )
This evaluates to the value 9.
Value = (GetData (BubbaBaes + BUBBA_HIGH_DATA) << 8) |
GetData (BubbaBaes + BUBBA_LOW_DATA);This block shall begin on the first line of the file. This is a Doxygen file descriptor comment block, so line 1 of the file will be:
/** @file
And the comment will end with:
**/
The File Heading comment block is comprised of the following sections: File Description, Copyright, License, and the optional Specification Reference and Glossary sections.
/** @file
File Description.
Copyright
License
Specification Reference
Glossary Section
**/The following example begins each body line with a tab (two spaces). This is the preferred indentation, but two tabs (four spaces) is also acceptable.
/** @file
Brief description of the file’s purpose.
Detailed description of the file’s contents and other useful
information for a person viewing the file for the first time.
Copyright (C) --20XX, Acme Corporation. All rights reserved.<BR>
SPDX-License-Identifier: BSD-2-Clause-Patent
@par Revision Reference:
- PI Version 1.0
@par Glossary:
- IETF - Internet Engineering Task Force
- NASA - National Aeronautics and Space Administration
**/The file description consists of a brief, one sentence, description of the file's purpose as well as a detailed description of the files purpose and content.
The brief description begins on the second line of the comment block and terminates at the first period. Do not include text indicating that the file is a header, include, declaration, or definition file as this is intrinsically obvious.
The detailed description follows the brief description, separated by a blank line. All subsequent text and blank lines are part of the detailed description until terminated by a Doxygen command or the end of the comment.
Note: The Copyright Notice and License comprise the last paragraph of the detailed file description. They are described separately, below.
The file description describes the purpose of the file (why the file exists), a general description of what it contains, and the relationship of the file to a particular module or modules, if any.
The first line of the last paragraph of the file description is made up of the
copyright notice. The copyright notice must consist of the following text with
the FIRST and LAST symbols replaced with the year the file was created and
the year the file was last edited, respectively.
Copyright (C) FIRST - LAST, Acme Corporation. All rights reserved.<BR>
A file that has been created but not edited in subsequent years would have a copyright notice with a single date, such as:
Copyright (C) 2007, Acme Corporation. All rights reserved.<BR>
If this file is subsequently edited, the copyright notice would be updated as follows.
Copyright (C) 2007 - 2014, Acme Corporation. All rights reserved.<BR>
The FIRST - LAST format for the copyright date, as described above, is the
only format allowed. Do not use a comma separated list or keep updating a
single date. The space surrounding the hyphen, '-', between the FIRST and
LAST dates is optional.
The <BR> at the end of the line is required. Doxygen uses XML for its
internal format, so repeated spaces and new lines are treated as a single
space. The <BR> will force Doxygen to start the following text, the license
notice, on a new line.
EDK II code files may contain one of several different licenses, depending upon the location and content of the file. The correct license will be determined by the project leader at the time the file is created. In most cases, the license will be the same as for other files in the module or package.
The preferred license for EDK II is the "BSD+Patent" license. The license for a file is provided in the file header using an SPDX identifier. The following shows the SPDX identifier for the "BSD+Patent" license.
SPDX-License-Identifier: BSD-2-Clause-Patent
The license follows the copyright notice. The license is separated from the Specification Reference, if present, by a single blank line.
If the file declares or implements something described in one or more UEFI or Industry Standard specifications, it must include a specification reference section in the file description comment block. The section begins with a Doxygen directive:
@par Revision Reference:
Each specification is listed on a separate line. All specification references must use the list format. An indented line beginning with a dash character, '-', indicates list format.
@par Revision Reference:
- UEFI Version 2.2
- PI Version 1.0
If the file uses a non-standard Abbreviation or Acronym, it must include a Glossary section in the file description comment block. The section begins with a Doxygen directive:
@par Glossary:
Each Glossary definition is listed on a separate line. All Glossary definitions must use the list format.
@par Glossary:
- IETF - the Internet Engineering Task Force
- NASA - National Aeronautics and Space Administration