Introduction to BDE Coding Standards
The coding standards used in the BDE libraries can be found here: BDE Coding Standards.
BDE software is characterized by a set of organizing principles, design rules, and implementation requirements, which make it highly interoperable, and give clients a uniform, predictable look-and-feel. The rules cover many aspects of software development (e.g., how to name and order things, documentation requirements, testing concerns); and address concerns at many levels (e.g., the relationship of components within a package, the organization of classes within a component, the design of interfaces for class methods, the layout of code within the implementation, the phrasing within function documentation, the commenting of class data members). The rules cover both "logical design" (how to define useful classes, functions, and data) and also what we call "physical design" (how to effectively partition software into files and libraries), a critical aspect of software engineering that is all too often not given formal consideration.
Bear in mind that the rules stated in this document are coding standards (i.e., requirements), not style guidelines. An explicit goal of BDE is that all software appears to have been designed and rendered by a single, highly qualified individual.
Our coding standards document enumerates many of these rules and is the authoritative reference for developers creating software for our libraries. Developers should also seek out the exemplar components in the BDE libraries for "live" examples showing these rules applied in practice.
The coding standards document will also be vital to developers contributing to the suite of BDE software tools that help create BDE software, and help check software compliance with our rules. Note that the coding standard assigns numbers to rules, and that those values can be cited to clarify error and warning messages to users.
This section will highlight some of the key topics covered in the coding standard.
The "component", the unit of both logical and physical design is defined
very early in the coding standard. Speaking very roughly, a component is a
.h/.cpp-file pair that satisfies four fundamental properties (see the
2nd rule in the "Component Design Rules"
here).
This early material also addresses when a developer should house more than one class within a component, how those classes must be named, and in what namespaces they must be defined. The relationship of a component to its package and packages to their package groups are also detailed.
Readers will learn the required organization of .h and .cpp files, which
includes the placement and ordering of class definitions, free operator
declarations, method definitions, and data members and method declarations
within each class definition. There are also prescribed code comments
(banners, tags) that label these different code sections.
Interfaces, both class methods and free functions, have requirements on how they are named, as well as on the order, types, and names of their parameters.
Documentation is a first-class concern in BDE software, not only because of its importance to end users and maintainers, but, since the contract of our software is defined in the source code documentation, it is a key part of our testing strategy. Note that code, documentation (including usage examples), and tests for a given component are typically developed concurrently by a single developer.
In particular, documentation for each function (method) must delineate, in the following order:
- what the function does,
- what it returns,
- any other essential behavior,
- any conditions leading to undefined behavior, and
- optionally, further clarifying (but not normative) statements.
There is standard phrasing for each part, and rules that allow some of these items to be combined in a single sentence.
Certain key terminology is defined precisely so that the terms can be used unambiguously throughout BDE source code documentation. These terms describe thread-, exception-, and alias-safety. Also described here is the BDE class taxonomy (e.g., value-semantic class, protocol, utility). These well-known exemplar names allow for economic descriptions in BDE documentation. For example, a class described as "This simply constrained (value-semantic) attribute class .." has a well-known set of features that need not be described in detail, and variances, if any, from the common pattern can be stated explicitly.
Finally, the coding standard specifies a super light-weight markup language
used in BDE source code comments. This language (called bdeml for "BDE
Markup Language") has features for denoting document sections, headings within
sections, font changes for words, delimiting code displays, lists (ordered and
not), and links within our source code documentation.
The BDE coding standards have been used in thousands of components for more than a decade at Bloomberg. The standards are stable, however they are not static. The standard has evolved and will continue to evolve (slowly) as our experience grows, and certainly as we begin to use features introduced in C++11. The coding standard document will be updated accordingly.
If you have questions, comments, suggestions for improvement or any other inquiries regarding BSL or this wiki, feel free to open an issue in the issue tracker.
