- You can almost always use an inline function or class instead of a macro. Use a macro only when you really need it.
- Templates may be preferable to multi-line macros. (There may be subtle performance effects with templates on some platforms; revert to macros if absolutely necessary.)
- For build features such as
#ifdef PRODUCTfor multiple-line inclusions or exclusions.
- For short inclusions or exclusions based on build features, use macros like
NOT_PRODUCT. But avoid using them with multiple-line arguments, since debuggers do not handle that well.
THROW, etc. for HotSpot-specific exception processing.
- Group related code together, so readers can concentrate on one section of one file.
- Avoid making functions too large, more than a screenful of text; split out chunks of logic into file-local classes or static functions if needed.
- If a class
FooBaris going to be used in more than one place, put it a file named
fooBar.cpp. If the class is a sidekick to a more important class
BazBat, it can go in
- Put a member function
FooBar::banginto the same file that defined
FooBar, or its associated
- Conform new code to style conventions. Avoid unnecessary "esthetic" variations, which are distracting.
- Use the C++ RAII design pattern to manage bracketed critical sections. See class
ResourceMarkfor an example.
+Verboseis used to provide additional output for another flag, but does not enable output by itself.
- Do not use ints or pointers as booleans with
while. Instead, compare explicitly
!= NULL, etc. (See #8 above.)
- Use functions from
globalDefinitions.hppwhen performing bitwise operations on integers. Do not code directly as C operators, unless they are extremely simple. (Examples:
- Naming JTreg tests
- More suggestions on factoring.
- Do not put non-trivial function implementations in .hpp files. If the implementation depends on other .hpp files, put it in a .cpp or a .inline.hpp file.
- .inline.hpp files should only be included in .cpp or .inline.hpp files.
- All .cpp files include precompiled.hpp as the first include line.
- precompiled.hpp is just a build time optimization, so don't rely on it to resolve include problems.
- Keep the include lines sorted.
- Put conditional inclusions (#if ...) at the end of the include list.
Occasionally a guideline mentioned here may be just out of synch with the actual Hotspot code base. That's why we're using a wiki to document the guidelines. If you find that a guideline is consistently contradicted by a large number of counterexamples, please mention it here, to assist the rest of us coders with making an informed decision about coding style. The architectural rule, of course, is "When in Rome do as the Romans". Sometimes in the suburbs of Rome the rules are a little different; these differences can be pointed out here.