Page History

...

• 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 PRODUCT, use #ifdef PRODUCT for multiple-line inclusions or exclusions.
• For short inclusions or exclusions based on build features, use macros like PRODUCT_ONLY and NOT_PRODUCT. But avoid using them with multiple-line arguments, since debuggers do not handle that well.
• Use CATCH, THROW, etc. for HotSpot-specific exception processing.

Grouping

...

• 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 FooBar is going to be used in more than one place, put it a file named fooBar.hpp and fooBar.cpp. If the class is a sidekick to a more important class BazBat, it can go in bazBat.hpp.
• Put a member function FooBar::bang into the same file that defined FooBar, or its associated *.cpp file.

...

• 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 ResourceMark for an example.
• +Verbose is used to provide additional output for another flag, but does not enable output by itself.
• Do not use ints or pointers as booleans with &&, ||, if, while. Instead, compare explicitly != 0 or != NULL, etc. (See #8 above.)
• Use functions from globalDefinitions.hpp when performing bitwise operations on integers. Do not code directly as C operators, unless they are extremely simple. (Examples: round_to, is_power_of_2, exact_log2.)
• Naming JTreg tests
• More suggestions on factoring.

Files

Anchor
Files Files

• 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.

Counterexamples

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.

...