Team2021Group19

h1. OnkoDICOM Naming Convention

_Authored by the OnkoDICOM 2020 Team_

_Written by Matthew Archer_

Draft v2 - 11/08/2020

h2. 1. Style

The stylization of all variables, classes, functions, docstrings, comments, etc. should all be compliant with the standards defined in the "PEP 8 Style Guide":https://www.python.org/dev/peps/pep-0008/ . This extends to indentation, tabs/spaces, maximum line length, blank lines between functions, and so on. The motivation behind PEP 8 adherence falls under two main reasons:

# PEP has been the agreed upon “universal” style guide for the Python programming language since its publication in 2001.

# PyCharm, the IDE of choice for the development of OnkoDICOM, has built-in formatting hints that assists the contributors in complying to the rules that the standard has drawn out.

It is important to point out the fact that the exact style guide that is chosen is not important, only that everything within a project is _consistent_ and _readable_ throughout (which is a key point noted by PEP). It is for that reason that there are slight deviations from the PEP 8 standard that will be defined below, as internal consistency is the primary goal.

The key aspects of PEP 8 that are most relevant to OnkoDICOM’s contributors are highlighted below. The deviations are italicized.

h3. 1.1 Functions and Variables

* Function names should be lowercase, with words separated by underscores as necessary to improve readability.

* Variable names follow the same convention as function names, except for constants which should be written in all capital letters with underscores separating words.

* mixedCase is allowed only in contexts where that's already the prevailing style (e.g. threading.py), to retain backwards compatibility.

h3. 1.2 Classes

* Class names should use the CapWords convention.

h3. 1.3 Packages and Modules

* Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

* _Module names should follow the CapWords convention._

h3. 1.4 Mixed Case

* mixedCase should only be used when calling from/extending libraries where it is already the prevailing style, or when child classes inherit a method/class variable that are defined using this stylization.

* In all other instances, mixedCase is not appropriate to use.

h2. 2. Naming

All names pertaining to functions, variables, classes, etc. must all have names that are _precise_, _readable_ and _unique_.

2.1 Choosing Names

* All names should use complete words with proper separation of words (underscores, CapsCase, etc.).

* Definite and indefinite articles (e.g. _the_, _a_, _an_, etc.) should be avoided.

* All words should be correctly spelled. If spelling of a word needs to be adjusted to avoid collision with another function or variable, then a more appropriate name should be considered.

* Names should be descriptive of what they do, and avoid ambiguity.

** For example, OnkoDICOM’s _PatientDictContainer_ class was previous called _DICOMData_.

** While DICOMData represented what the class contained and was responsible for, DICOMData is an incredibly vague name as many other classes also handled DICOM Data and the name was deemed inappropriate.

** PatientDictContainer was the preferred choice of name as it describes what the class does; it is a container of dictionaries relating to patient data.

2.2 Module Names

* When a module exists primarily to act as a containing file to define a new class (and occasionally children of that class), the module name should be identical to the name of the top-level class in the file.

** For example, OnkoDICOM’s _DICOMStructure_ module defines a top-level class called _DICOMStructure_, and then further defines classes representing children of the DICOMStructure: _Patient_, _Study_, _Series_, and _Image_.

* In all other cases where a module acts as a container for functions or a variety of classes, the module should be named to appropriately describe what links all the contained functions and classes. All functions and classes should be able to be described by a single module name.