diff --git a/doc/source/Getting_started/Contributing.rst b/doc/source/Getting_started/Contributing.rst index c7392e86e40..b62237fa983 100644 --- a/doc/source/Getting_started/Contributing.rst +++ b/doc/source/Getting_started/Contributing.rst @@ -41,12 +41,13 @@ for switching from viewing the documentation for the latest stable release to viewing the documentation for the development version or previously released versions. -Adhere to code style --------------------- -PyAEDT is compliant with `PyAnsys code style -`_. It uses the tool -`pre-commit `_ to check the code style. You can install -and activate this tool with: +Code style +---------- +PyAEDT complies with the `PyAnsys code style +`_. +`pre-commit `_ is applied within the CI/CD to ensure compliance. +The ``pre-commit`` Python package can be installed +and run as follows: .. code:: bash @@ -73,6 +74,56 @@ For example:: Validate GitHub Workflows................................................Passed blacken-docs.............................................................Passed +Naming conventions +~~~~~~~~~~~~~~~~~~ +Consistency of names helps improve readability and +ease of use. Starting with release 0.8 a concerted effort +has been made to +improve consistency of naming and adherence to +:ref:`PEP-8`_. + +For example, methods used to create or access entities in +AEDT require that a name be passed to the method or function +as an argument. +It is tempting to +include context as part of that variable name. For example, while it is tempting to use +``setupname`` +as an argument to :meth:`Hfss.create_setup`_, +the context "setup" is +explicitly defined by the method name. The variable ``name`` provides +a more compact +description of the variable in this context. + +In previous PyAEDT versions, you can also find both ``setup_name`` and ``setupname`` used +for various methods or classes. +Improving naming consistency improves maintainability and readability. + +The following table illustrates the recommended conventions: + +.. list-table:: Keywords and object names + :widths: 25 25 50 + :header-rows: 1 + + * - Old name + - New name + - Example + * - ``setupname``, ``setup_name``, ``sweepname`` + - ``name`` + - ``Hfss.create_setup()``, ``Hfss.create_linear_step_sweep()`` + * - ``usethickness`` + - ``thickness`` + - ``Hfss.assign_coating()`` + * - ``entities`` + - ``assignment`` + - ``Maxwell.assign_current_density()`` + * - ``entity_list`` + - ``assignment`` + - ``Maxwell.assign_symmetry()`` + +Take care to use descriptive names for +variables and classes that adhere to PEP-8 and are consistent with conventions already +used in PyAEDT. + Log errors ~~~~~~~~~~ PyAEDT has an internal logging tool named ``Messenger``