A program is meant to be read by the programmer, by another programmer at a future date, and by a machine. In this sense it is a kind of publication.
However, the machine is concerned with whether the program compiles, while people are necessarily concerned about coding conventions or style.
Sensible and consistently applied typographic (stylistic) conventions are important to the creation of a clear presentation. Conventions are created to facilitate clarity, should not become an end in and of themselves. As Rob Pike points out, we should avoid typographic silliness and decoration:" . . . keep comments brief and banner free. Say what you want to say in the program, neatly and consistently. Then move on."
The EDK II code documentation shall fulfill the following main functions:
It shall serve as:
Working instructions (e.g. error and interrupt handling, data archiving, ...)
A working basis to avoid duplication of work
A working basis for software maintenance (e.g. updates, upgrades, troubleshooting)
A basis for brief instruction and training of new staff members; simple training courses
Establishes traceability between the code and product requirements
Reference for internal and external auditors (product liability, ISO 9001 certification)
Facilitates project management and monitoring
Increases testability of the software
Establishes an uniform communication basis for:
All software developers
Contractors and customers
Increases software re-usability
Increases transparency of the software
The EDK II architecture forces explicit documentation as it encourages the use of multiple, independent modules. The mechanism for these modules to communicate is a protocol. A protocol is an instance of an API (a class in C++ vernacular) that is named by a GUID. The GUID defines the data representation and member functions of a protocol. Any change to the behavior of a protocol requires the GUID to change. Given this property, each protocol used in EDK II must have an interface document.