Design Philosophy and Style Guide#

Design Philosophy#

  1. Do Not Repeat Yourself (DRY)

  2. If it’s worth doing, it’s worth doing well.

  3. Use abstraction and inheritance smartly.

  4. Use @property getters, and if needed setters. Setters must verify and clean user inputs. For the most part use make_prop_val_node(), and make_prop_pointer().

  5. Fail early and politely. If there’s something that might be bad: the user should get a helpful error as soon as the error is apparent.

  6. Test. test. test. The goal is to achieve 100% test coverage. Unit test first, then do integration testing. A new feature merge request will ideally have around a dozen new test cases.

  7. Do it right the first time.

  8. Document all functions.

  9. Expect everything to mutate at any time.

  10. Avoid relative imports when possible. Use top level ones instead: e.g., import montepy.cell.Cell.

  11. Defer to vanilla python, and only use the standard library. Currently the only dependencies are numpy and sly. There must be good justification for breaking from this convention and complicating things for the user.

Style Guide#

  1. Thou shall be PEP 8, and use black.

  2. Spaces not tabs with 4 spaces for an indent.

  3. External imports before internal imports with a blank line in between. All imports are alphabetized.

Naming Conventions#

  1. Follow PEP 8 naming conventions e.g.,

    1. lower_case_with_underscores for variables, methods, functions, and module names, etc.

    2. CapitalizedWords for class names

      • MCNP_ClassName is an exception. For all Other acronyms use: AcronymMoreWords. Above all, prioritize legibility.

    3. UPER_CASE_WITH_UNDERSCORES for pseudo-constant variables

    4. _single_leading_underscore should be used for almost all internal attributes.

    5. __double_leading_underscore should be used for private internal attributes that should not be accessed by users or sub-classes.

  2. Variables should be nouns/noun-phrases

  3. Functions/methods should be verb/verb-phrases.

  4. Properties/attributes of classes should be nouns or is_adjective phrases.

  5. Collections should be a plural noun, and single instances should be singular. In loops there should be consistent names, e.g., for cell in cells:.

  6. When appropriate names should mirror Python core libraries (e.g., NumberedObjectCollection tries to mirror methods of dict, list, and set).

  7. Within reason: avoid abbreviating words. Above all, prioritize legibility.

  8. For user facing functions and attributes, short names are best. (surface_constants, really should have been constants in hind-sight).