|
Use the following coding guidelines when making code changes to OpenUSD.
Code should follow the formatting rules:
if
, for
, while
, and similar control-flow statements that have a single line in their bodies. Always put the body code for a function or control-flow statement on a separate line. UsdLuxLightFilter
). ReadImage()
). If possible, prefix method and function names with a verb. imageData
). _PrivateMethod()
, _privateData
). PXR
namespace. To do this: PXR_NAMESPACE_OPEN_SCOPE
at the top of every C++ file, header and cpp, after the includes. PXR_NAMESPACE_CLOSE_SCOPE
at the bottom of every C++ file, header and cpp. PXR_NAMESPACE_USING_DIRECTIVE
at the top of any C++ test code, after the includes. Protect header files from multiple inclusion by using guard macros, using a macro name of the form PACKAGENAME_HEADERNAME_H
. For example, in pxr/usd/usd/tokens.h
the following guard macros are used:
Use guard macros rather than #pragma once
directives.
LIBNAME_API
macro for your library (e.g. USD_API
, SDF_API
, etc). LIBNAME_API_CLASS
rather than LIBNAME_API
for code-search purposes. LIBNAME_API
macro for any declaration you need to export. This will typically include: template<>
with empty parameters). LIBNAME_API
macro on declarations, not definitions. It should be added after template
, class
, and/or struct
, if present, and before static
and/or virtual
, if present, and before the symbol's type. For classes, you'll typically mark individual methods/members, and not entire classes, although small public structs may be exported in their entirety. License header: please add this text at the top of each new source file (in comments):
Keep your changes small and atomic so it's easier to do code reviews, and, if necessary, to troubleshoot regressions.
For example, split features into their own changelists; split API changes and behavior changes into different changelists; split schema changes and implementation into different changelists. Splitting up larger changes makes it easier and less risky to incorporate these changes into the codebase.
All code changes should have proper test coverage to ensure code quality. See Testing Guidelines for OpenUSD for more information on writing tests.
Changes should be accompanied by API documentation and user documentation, if applicable, to help other developers and users make the most of your changes.
If you are adding new or modifying existing APIs, please update the corresponding documentation. This should be completed prior to getting a code review, so the reviewer has more context and can also help identify anything in the documentation that may cause confusion.
For C++ code we use doxygen-style comments for documentation and generate HTML documentation from these comments.
If you are adding or updating USD schemas that will get generated into C++ code from the schema.usda file (i.e. not codeless schemas), you should add your API documentation (in doxygen-style format) in the "doc" metadata field string of the schema class or attribute. These strings will be converted into C++ comments in the generated code (via usdGenSchema.py).
User documentation is usually written in reStructured Text (as .rst files) or Myst Markdown (as .md files) format, and generated into HTML using Sphinx. Content files and Sphinx scripts are currently in the docs/
directory.
If you are adding or updating USD schemas, you should also add user documentation for the schema classes and properties using the "userDocBrief" and "userDoc" custom metadata fields. See docs/README.md
for more details.