Detail coding standards (C++/CMAKE/Python/pybind11)

[nicklafarge]

Need a comprehensive set of coding standards to allow for straight-forward committing. Once decided, these should all be listed in the wiki.

C++/CMAKE:

• Set up the root-level clang format file to enable automatic formatting
• Set up the root-level clang tidy for naming conventions
• Identify set of naming conventions and other misc. coding conventions to follow
• Document conventions
• Set up CI checks to ensure pull requests are formatted and clang tidy passes

Python:

• Decide on standards/conventions for pybind11 implementation/enforcement
• Set up flake8 for PEP 8 checking

Matlab:

• Define Matlab standards (will these be enforced)?

[rjpower4]

@nicklafarge, do you think that the conventions should go in the wiki or? I'm talking about the things not enforced by clang format

[nicklafarge]

@nicklafarge, do you think that the conventions should go in the wiki or? I'm talking about the things not enforced by clang format

I think maybe we need some sort of "contributing guide" as a part of the public-facing documentation that includes these sorts of standards definitions

[DhruvJ22]

Drake might be a good source to refer to for a contributing guide, coding style, and test setup as their codebase is primarily in C++ with a Python extension. It is highly reliable as it is maintained by TRI.

[nicklafarge]

Drake might be a good source to refer to for a contributing guide, coding style, and test setup as their codebase is primarily in C++ with a Python extension. It is highly reliable as it is maintained by TRI.

This might be helpful for #9 too

[rjpower4]

We'll also need some sort of formatting stuff for python. Ideas? @nicklafarge, @DhruvJ22, @noahsadaka?

[DhruvJ22]

PEP 8 and for docstrings PEP 257? Check this out - drake quide

[noahsadaka]

flake8 for Python is a module you can run your python files through that checks for PEP 8 compliance. Could make it a requirement when submitting a pull request containing python code to run it through flake8 first and making it all PEP 8 compliant.

[nicklafarge]

Yes on PEP 8. However, the part that will complicate this is that most of the Python functionality will be written in C++, So it's a question of writing C++ code that adheres to C++ standards, but produces Python functionality that adheres to Python standards (naming contentions, documentation, etc). I found this pybind11 style guide from another project which could be useful for us to emulate. For documentation, I see that pybind11 supports sphynx, so that is something to consider using as well. I think flake8 is a good ideafor pull requests/our CI pipeline, but its impact will be limited to our example scripts and python unit testing, i.e. not pybind11 side of things. My guess is we are on our own with enforcing those standards there.

Thoughts?

[DhruvJ22]

I have an idea that we can use for pybind11 side of things. I will flesh it out and share it with you by tomorrow.

[rjpower4]

The auto-formatting and validation of coding standards for the example cases and testing is justification of the tooling for me. Also, I would not be surprised if there were some small shimming in python that gets added over time.

[nicklafarge]

Yeah, agreed. flake8 sounds good to me