Code Guide and Tips

This is a document used to record tips in MXNet codebase for reviewers and contributors. Most of them are summarized through lessons during the contributing and process.

C++ Code Styles

  • Use the clang-format to reformat your code.
  • The public facing functions are documented in doxygen format.
  • Favor concrete type declaration over auto as long as it is short.
  • Favor passing by const reference (e.g. const Expr&) over passing by value. Except when the function consumes the value by copy constructor or move, pass by value is better than pass by const reference in such cases.
  • Favor const member function when possible.
  • Use RAII to manage resources, including smart pointers like shared_ptr and unique_ptr as well as allocating in constructors and deallocating in destructors. Avoid explicit calls to new and delete when possible. Use make_shared and make_unique instead.

We use cpplint to enforce the code style. Because different version of cpplint might change by its version, it is recommended to use the same version of the cpplint as the master. You can also use the following command via docker.

ci/build.py -R --docker-registry mxnetci --platform ubuntu_cpu --docker-build-retries 3 --shm-size 500m /work/runtime_functions.sh sanity_cpp

cpplint is also not perfect, when necessary, you can use disable cpplint on certain code regions.

Python Code Styles

  • The functions and classes are documented in numpydoc format.
  • Check your code style using make pylint
  • Stick to language features as in python 3.6 and above.

Testing

Our tests are maintained in the /tests folder. We use the following testing tools:

  • For Python, we use pytest.
    • An example of setting up and running tests (tested on MacOS with Python 3.6):
      • follow the build from source guide to build MXNet
      • install python libraries 
        python3 -m pip install opencv-python
python3 -m pip install -r ci/docker/install/requirements
      • install MXNet Python bindings: 
        python3 -m pip install -e ./python
      • run tests in a specific module 
        python3 -m pytest tests/python/unittest/test_smoke.py
      • or run a specific test in a module 
        python3 -m pytest tests/python/unittest/test_smoke.py::test_18927
      • or run all the Python unittests 
        python3 -m pytest tests/python/unittest/
  • For C++, we use gtest.

Our CI pipelines check for a wide variety of configuration on all platforms. To locate and reproduce a test issue in PR, you can refer to the process described in #18723