This document provides guidance for the kind of code that should go in to the Hermes project. The rules in this document will allow us to scale the project and ensure that the code base remains readable and maintainable.
Hermes uses C++11.
Exceptions or RTTI are prohibited, except where needed for interfacing with other software that requires them.
GCC language extensions are discouraged for compatibility with MSVC, or they should be conditionally enabled.
TODO: This should be sorted and expanded.
- Every declaration must have a doc-comment.
- Member variables use a "_" suffix unless they are public, where it is acceptable to omit the suffix.
- Classes use pascal case (
- Functions and methods use camel case (
- Variables generally use camel case (
myVar). We also allow "abbreviated case": "basic block" can be abbreviated as
BB, "instruction" can be abbreviated as
- Constants use either capitalized snake case (
MY_CONST) or camel case with "k" prefix (
structshould be used only when it is a true POD - there are no constructors or destructors of any kind. For everything else use
- Inlining: Only completely trivial (one line) methods can be defined in the
class body. The rest should be declared as
inlineboth at the declaration and the definition.
The project is developed using small incremental changes. These changes can be small bug fixes or minor tweaks. Other times, these changes are small steps along the path to reaching larger stated goals. Long-term development branches suffer from many problems, including the lack of visibility, difficulty of code review, lack of testing of the branch and merge difficulty.
Commits that go into the project need to be reviewable. This means that commits need to be relatively small, well documented and self contained.
Functional changes to the compiler need to include a testcase. Unit tests and regression tests are critical to the qualification of the compiler. Every bug fix needs to include a testcase.
Reduce test cases as much as possible! It is unacceptable to commit big programs because they do not describe the essence of the failure, they are fragile, and they slow testing down. Tests need to be short and focused.
clang-format is required to enforce code style and formatting. Commits that only change the formatting of code should go in independent of functional changes.
Here are some guidelines about the format of the commit message:
Separate the commit message into a single-line title and a separate body that describes the change. Make the title short (80 chars) and readable. In changes that are restricted to a specific part of the code, include a [tag] at the start of the line in square brackets—for example, “[docs] ... ”.
If the commit fixes an issue in the bug tracking system, include a link or a task number.
When reverting a change make sure to add a short note that describes why the patch is being reverted.
The project relies heavily on code review to maintain the software quality.
Review other people’s changes! Anybody is allowed to review code and comment on patches.
All changes, by all developers, must be reviewed before they are committed to the repository. Smaller changes (if the developer is the de-facto owner of the code base) can be reviewed after being committed.