Skip to content

Latest commit

 

History

History
403 lines (327 loc) · 19.3 KB

codingGuidelines.md

File metadata and controls

403 lines (327 loc) · 19.3 KB
Raw

This document outlines coding guidelines for contributions to the maya-usd project.

C++ Coding Guidelines

Many of the C++ coding guidelines below are validated and enforced through the use of clang-format which is provided by the LLVM project. Since the adjustments made by clang-format can vary from version to version, we standardize this project on a single clang-format version to ensure consistent results for all contributions made to maya-usd.

Version Source Code Release
clang-format/LLVM 10.0.0 llvmorg-10.0.0 Tag LLVM 10.0.0

Foundation/Critical

License notice

Every file should start with the Apache 2.0 licensing statement:

// Licensed under the Apache License, Version 2.0 (the “License”);
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an “AS IS” BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

Copyright notice

  • Every file should contain at least one Copyright line at the top, which can be to Autodesk or the individual/company that contributed the code.
  • Multiple copyright lines are allowed, and if a significant new contribution is made to an existing file then an individual or company can append a new line to the copyright section.
  • The year the original contribution is made should be included but there is no requirement to update this every year.
  • There is no requirement that an Autodesk copyright line should be in all files. If an individual or company contributes new files they do not have to add both their name and Autodesk's name.
  • If existing code is being refactored or moved within the repo then the original copyright lines should be maintained. You should only append a new copyright line if significant new changes are added. For example, if some utility code is being moved from a plugin into a common area, and the work involved is only minor name changes or include path updates, then the original copyright should be maintained. In this case, there is no requirement to add a new copyright for the person that handled the refactoring.

#pragma once vs include guard

Do not use #pragma once to avoid files being #include’d multiple times (which can cause duplication of definitions & compilation errors). While it's widely supported, it's a non-standard and non-portable extension. In some cases using #pragma once may include two copies of the same file when they are accessible via multiple different paths.

All code should use include guards instead #pragma once. For example:

// file foobar.h:
#ifndef LIBRARY_FOOBAR_H
#define LIBRARY_FOOBAR_H
// … declarations …
#endif // LIBRARY_FOOBAR_H

Never use reserved identifiers, like underscore followed immediately by an uppercase letter or double underscore. For example, the following is illegal:

// file foobar.h:
#ifndef __LIBRARY_FOOBAR_H
#define __LIBRARY_FOOBAR_H
// … declarations …
#endif // __LIBRARY_FOOBAR_H

// file foobar2.h:
#ifndef _LIBRARY_FOOBAR2_H
#define _LIBRARY_FOOBAR2_H
// … declarations …
#endif // _LIBRARY_FOOBAR2_H

Naming (file, type, variable, constant, function, namespace, macro, template parameters, schema names)

General Naming Rules MayaUsd strives to use “camel case” naming. That is, each word is capitalized, except possibly the first word:

  • UpperCamelCase
  • lowerCamelCase

While underscores in names (_) (e.g., as separator) are not strictly forbidden, they are strongly discouraged. Optimize for readability by selecting names that are clear to others (e.g., people on different teams.) Use names that describe the purpose or intent of the object. Do not worry about saving horizontal space. It is more important to make your code easily understandable by others. Minimize the use of abbreviations that would likely be unknown to someone outside your project (especially acronyms and initialisms).

File Names Filenames should be lowerCamelCase and should not include underscores (_) or dashes (-). C++ files should end in .cpp and header files should end in .h. In general, make your filenames as specific as possible. For example:

stageData.cpp
stageData.h

Type Names All type names (i.e., classes, structs, type aliases, enums, and type template parameters) should use UpperCamelCase, with no underscores. For example:

class MayaUsdStageData;
class ImportData;
enum Roles;

Variable Names Variables names, including function parameters and data members should use lowerCamelCase, with no underscores. For example:

const MDagPath& dagPath
const MVector& rayDirection
bool* drawRenderPurpose

Class/Struct Data Members Non-static data members of classes/structs are named like ordinary non-member variables with leading “_”. For example:

UsdMayaStageNoticeListener _stageNoticeListener;
std::map<UsdTimeCode, MBoundingBox> _boundingBoxCache;

For static data members the leading underscore should be omitted.

static const MTypeId typeId;

Constant Names Variables declared constexpr or const, whose value is fixed for the duration of the program, should be named with a leading “k” followed by UpperCamelCase. For example:

const int kDaysInAWeek = 7;
const int kMyMagicNumber = 42;

Function/Method Names All functions should be lowerCamelCase. This avoids inconsistencies with the MayaAPI and virtual methods. For example:

MString name() const override;
void registerExitCallback();

Namespace Names Namespace names should be UpperCamelCase. Top-level namespace names are based on the project name.

namespace MayaAttrs {}

Enumerator Names Enumerators (for both scoped and unscoped enums) should be named like constants (i.e., kEnumName.)

The enumeration name, StringPolicy is a type and therefore mixed case.

enum class StringPolicy
{
  kStringOptional,
  kStringMustHaveValue
};

Macro Names In general, macros should be avoided (see Modern C++ ). However, if they are absolutely needed, macros should be all capitals, with words separated by underscores.

#define ROUND(x) …
#define PI_ROUNDED 3.0

Schema Names <Not yet defined, proposals are welcome>

Documentation (class, method, variable, comments)

  • Doxygen will be used to generate documentation from mayaUsd C++ sources.
  • Doxygen tags must be used to document classes, function parameters, function return values, and thrown exceptions.
  • The mayaUsd project does require the use of any Doxygen formatting style ( Doxygen built-in formatting )
  • Comments for users of classes and functions must be written in headers files. Comments in definition files are meant for contributors and maintainers.

Namespaces

In header files (e.g. .h)

  • Required: to use fully qualified namespace names. Global scope using directives are not allowed. Inline code can use using directives in implementations, within a scope, when there is no other choice (e.g. when using macros, which are not namespaced).
// In aFile.h
inline PXR_NS::UsdPrim prim() const
{
    PXR_NAMESPACE_USING_DIRECTIVE
    TF_VERIFY(fItem != nullptr);
    return fItem->prim();
}

In implementation files (e.g. .cpp)

  • Recommended: to use fully qualified namespace names, unless clarity or readability is degraded by use of explicit namespaces, in which case a using directive is acceptable.
  • Recommended: to use the existing namespace style, and not make gratuitous changes. If the file is using explicit namespaces, new code should follow this style, unless the changes are so significant that clarity or readability is degraded. If the file has one or more using directives, new code should follow this style.

Include directive

For source files (.cpp) with an associated header file (.h) that resides in the same directory, it should be #include'd with double quotes and no path. This formatting should be followed regardless of with whether the associated header is public or private. For example:

// In foobar.cpp
#include "foobar.h"

All included public header files from outside and inside the project should be #include’d using angle brackets. For example:

#include <pxr/base/tf/stringUtils.h>
#include <mayaUsd/nodes/stageData.h>

Private project’s header files should be #include'd using double quotes, and a relative path. Private headers may live in the same directory or sub-directories, but they should never be included using "." or ".." as part of a relative path. For example:

#include "privateUtils.h"
#include "pvt/helperFunctions.h"

Include order

Headers should be included in the following order, with each section separated by a blank line and files sorted alphabetically:

  1. Related header
  2. All private headers
  3. All public headers from this repository (maya-usd)
  4. UsdUfe library headers
  5. Pixar + USD headers + special pxr_python.h
  6. Autodesk + Maya headers
  7. Other libraries' headers
  8. C++ standard library headers
  9. C system headers
  10. Conditional includes
#include "exportTranslator.h"

#include "private/util.h"

#include <mayaUsd/fileio/jobs/jobArgs.h>
#include <mayaUsd/fileio/jobs/writeJob.h>
#include <mayaUsd/fileio/shading/shadingModeRegistry.h>
#include <mayaUsd/fileio/utils/writeUtil.h>

#include <usdUfe/ufe/UsdSceneItem.h>

#include <maya/MFileObject.h>
#include <maya/MGlobal.h>
#include <maya/MSelectionList.h>
#include <maya/MString.h>

#include <string>

#ifdef UFE_V3_FEATURES_AVAILABLE
#include <ufe/types.h>
#endif

Cross-platform development

  • Consult the build.md compatibility table to ensure you use the recommended tool (i.e., compiler, operating system, CMake, etc.) versions.
  • Before pull requests (PRs) are considered for integration, they must compile and all tests should pass on all suppported platforms.

Conditional compilation (Maya, USD, UFE version)

Maya * MAYA_API_VERSION is the consistent macro to test Maya version (MAYA_APP_VERSION * 10000 + MAJOR_VERSION * 100 + MINOR_VERSION) * MAYA_APP_VERSION is a simple year number, so it is not allowed in C++ code. However it is set as a CMake variable and allowed in cmake files.

UFE * Each version of Ufe contains a features available define (in ufe.h) such as UFE_V4_FEATURES_AVAILABLE that can be used for conditional compilation on code depending on Ufe Version.

USD * PXR_VERSION is the macro to test USD version in C++ code (PXR_MAJOR_VERSION * 10000 + PXR_MINOR_VERSION * 100 + PXR_PATCH_VERSION), ex: #if PXR_VERSION <= 2311 * USD_VERSION is the cmake variable to test USD version in cmake code, ex: if(USD_VERSION VERSION_LESS "0.24.11")

Respect the minimum supported version for Maya and USD stated in build.md .

std over boost

Recent extensions to the C++ standard introduce many features previously only found in boost. To avoid introducing additional dependencies, developers should strive to use functionality in the C++ std over boost. If you encounter usage of boost in the code, consider converting this to the equivalent std mechanism. Our library currently has the following boost dependencies:

  • boost::python for USD version < 24.11
  • boost::make_shared (preferable to replace with std::shared_ptr), boost::static_pointer_cast
  • boost::hash{_range/_value}, boost::mpl, boost::multi_index, boost::optional

Note: all these Boost dependencies are header only and thus don't require linking to actual Boost libraries.

Update:

  • boost::filesystem and boost::system are removed. Until the transition to C++17 std::filesystem, ghc::filesystem must be used as an alternative across the project.

  • Dependency on boost::thread is removed from Animal Logic plugin.

  • boost::hash_combine is replaced with MayaUsd::hash_combine and should be used instead across the project.

USD version >= 24.11:

  • In USD v24.11 Pixar has removed Boost as a dependency for the USD build. This includes Boost python which is no longer used to build the python bindings. Instead Pixar has created their own boost python in a separate pxr/external/boost folder. Since MayaUsd supports many versions of USD we have created a boost porting python file pxr_python.h. This file has uses ifdef checks to support all versions of USD and which python it uses. Not python (Boost or Pixar Boost) header files should be included directly in C++ source files. Instead always include only <pxr_python.h> and use the PXR_BOOST_PYTHON_NAMESPACE define to refer to the Boost python code, ex: PXR_BOOST_PYTHON_NAMESPACE::object

Modern C++

Our goal is to develop maya-usd following modern C++ practices. We’ll follow the C++ Core Guidelines and pay attention to:

  • using (vs typedef) keyword
  • virtual, override and final keyword
  • default and delete keywords
  • auto keyword
  • initialization - {}
  • nullptr keyword
  • …

Diagnostic Facilities

Developers are encouraged to use TF library diagnostic facilities in Maya USD. Please follow below guideline for picking the correct facility: https://graphics.pixar.com/usd/docs/api/page_tf__diagnostic.html

In MayaUSD, UsdMayaDiagnosticDelegate converts TF diagnostics into native Maya infos, warnings, and errors. The environment flag MAYAUSD_SHOW_FULL_DIAGNOSTICS, controls the granularity of TF error/warning/status messages being displayed in Maya:

e.g

Error: Failed verification: ' image ' -- Unable to create an image from RetroTVBody_Albedo.png

vs

Error: Failed verification: ' image ' -- Unable to create an image from RetroTVBody_Albedo.png -- Coding Error in _LoadTexture at line 422 of C:\maya-usd\lib\mayaUsd\render\vp2RenderDelegate\material.cpp

Coding guidelines for Python

We are adopting the PEP-8 style for Python Code with the following modification:

  • Mixed-case for variable and function names are allowed

Pylint is recommended for automation.

Coding guidelines for CMake

Modern CMake

  1. Target Build and Usage requirements should be very clear.
  • build requirements ( everything that is needed to build the target )
  • usage requirements ( everything that is needed to use this target as a dependency of another target)
  1. Always use target_xxx() and make sure to add the PUBLIC/PRIVATE/INTERFACE keywords as appropriate.
  • target_sources
  • target_compile_definitions
  • target_compile_options
  • target_include_directories
  • target_link_libraries
  • ...

Keyword meanings:

  • PRIVATE: requirement should apply to just this target.
  • PUBLIC: requirement should apply to this target and anything that links to it.
  • INTERFACE: requirement should apply just to things that link to it.
  1. Don't use Macros that affect all targets (e.g add_definitions, link_libraries, include_directories).
  2. Prefer functions over macros whenever reasonable.
  3. Treat warnings as errors.
  4. Use cmake_parse_arguments as the recommended way for parsing the arguments given to the macro or function.
  5. Don't use file(GLOB).
  6. Be explicit by calling set_target_properties when it's appropriate.
  7. Links against GTest using imported targets rather than variables: ex: GTest::GTest

Compiler features/flags/definitions

  1. Setting or appending compiler flags/definitions via CMAKE_CXX_FLAGS is NOT allowed.
  2. Any front-end flags (e.g. -Wno-xxx, cxx_std_xx) should be added to cmake/compiler_config.cmake.
  3. All current targets, as well as newly added targets, must use mayaUsd_compile_config function in order to get the project-wide flags/definitions. These flags/definitions are added privately via target_compile_features, target_compile_options, target_compile_definitions. Individual targets are still allowed to call target_compile_definitions, target_compile_features individually for any additional flags/definitions by providing appropriate PUBLIC/INTERFACE/PRIVATE keywords. For example:
# -----------------------------------------------------------------------------
# compiler configuration
# -----------------------------------------------------------------------------
add_library(${UFE_PYTHON_TARGET_NAME} SHARED)
target_compile_definitions(${UFE_PYTHON_TARGET_NAME}
   PRIVATE
       MFB_PACKAGE_NAME=${UFE_PYTHON_MODULE_NAME}
       MFB_ALT_PACKAGE_NAME=${UFE_PYTHON_MODULE_NAME}
       MFB_PACKAGE_MODULE="${PROJECT_NAME}.${UFE_PYTHON_MODULE_NAME}"
)
mayaUsd_compile_config(${UFE_PYTHON_TARGET_NAME})

Dynamic linking and Run-time Search Path

Use provided mayaUsd_xxx_rpath() utility functions to handle run-time search path for both MacOSX and Linux.

Unit Test

  1. Use provided mayaUsd_add_test() function for adding either Gtest or Python tests.
  2. Don't add find_package(GTest REQUIRED) in every CMake file with unit tests. Gtest setup is handled automatically for you.
  3. For targets that need to link against google test library. Simply add GTest::GTest to target_link_libraries. You don't need to add any Gtest include directory this is done automatically for you.

Naming Conventions

  1. CMake commands are case-insensitive. Use lower_case for CMake functions and macros, use upper_case for CMake variables.
# e.g cmake functions
add_subdirectory(schemas)
target_compile_definitions(....)

# e.g cmake variables
${CMAKE_CXX_COMPILER_ID}
${CMAKE_SYSTEM_NAME}
${CMAKE_INSTALL_PREFIX}
  1. Use upper_case for Option names.
# e.g for options names
option(BUILD_USDMAYA_SCHEMAS "Build optional schemas." ON)
option(BUILD_TESTS "Build tests." ON)
option(BUILD_STRICT_MODE "Enforce all warnings as errors." ON)
  1. Use upper_case for Custom variables.
# e.g for options names
set(BUILD_WITH_PYTHON_3_VERSION 3.7 CACHE STRING "The version of Python 3 to build with")
 
set(HEADERS
    jobArgs.h
    modelKindProcessor.h
    readJob.h
    writeJob.h
)
 
set(RESOURCES_INSTALL_PATH ${CMAKE_INSTALL_PREFIX}/lib/usd/${TARGET_NAME}/resources)
 
set(USDTRANSACTION_PYTHON_LIBRARY_LOCATION ${AL_INSTALL_PREFIX}/lib/python/AL/usd/transaction)
  1. Respect third-party variables (don't change them).
# e.g boost
set(BOOST_ROOT ${pxr_usd_location})
set(Boost_USE_DEBUG_PYTHON ON)
  1. Avoid adding the optional name in endfunction/endmacro([]).

Although there is no official guideline for Modern CMake practices, the following resources provide ample information on how to adopt these practices: Modern cmake, Effective Modern CMake