Style Guide and General Conventions#

We automatically reformat all contributions using the black pre-commit hook formatter. Black enforces strict rules about spacing to produce minimal diffs. To enable black formatting on your own machine, do the following:

  1. Install pre-commit: pip install pre-commit

  2. Execute pre-commit install to install git hooks in your .git/ directory.

Scikit-learn style#

Beyond using black, this project follows some of the conventions from scikit-learn.

  1. Use underscores to separate words in non class names: n_samples rather than nsamples.

  2. Avoid multiple statements on one line. Prefer a line return after a control flow statement (if/for). Note that this does not apply to conditional expressions

  3. Use relative imports for references inside the source code src/neuroconv.

  4. Unit tests are an exception to the previous rule; they should use absolute imports, exactly as client code would.

  5. A corollary is that, if neuroconv.foo exports a class or function that is implemented in neuroconv.foo.bar.baz, the test should import it from neuroconv.foo.

  6. Please dont use import * in any case. It is considered harmful by the official Python recommendations. It makes the code harder to read as the origin of symbols is no longer explicitly referenced, but most important, it prevents using a static analysis tool like pyflakes to automatically find bugs in the code.

  7. Use the numpy docstring standard in all the docstrings.

DataInterface conventions#

  1. Use file_path and folder_path as arguments for the location of input files and folders/directories respectively.

  2. As an exception to convention to separate words for underscores, we use nwbfile to refer to an instance of NWBFile.

Other conventions#

  1. Whenever possible, use the type dictionary constructor dictionary = dict(foo=bar) instead of the brace notation dictionary={foo: bar}. Notable exceptions that do not lend themselves to this constructor are the use of non-valid python expressions as keys (e.g 1key can not be used as a key because of the number at the beginning) and the use of non-mutable objects as keys.

  2. Use “NWBFile” when referring to an instance of NWBFile. Use “NWB File” when referring to a file that is in the NWB format.