... | ... | @@ -13,9 +13,7 @@ Correct: |
|
|
|
|
|
```python
|
|
|
# Aligned with opening delimiter.
|
|
|
|
|
|
foo = long_function_name(var_one, var_two,
|
|
|
|
|
|
var_three, var_four)
|
|
|
```
|
|
|
|
... | ... | @@ -23,38 +21,26 @@ foo = long_function_name(var_one, var_two, |
|
|
|
|
|
```python
|
|
|
def long_function_name(
|
|
|
|
|
|
var_one, var_two, var_three,
|
|
|
|
|
|
var_four):
|
|
|
|
|
|
print(var_one)
|
|
|
|
|
|
# Hanging indents should add a level.
|
|
|
|
|
|
foo = long_function_name(
|
|
|
|
|
|
var_one, var_two,
|
|
|
|
|
|
var_three, var_four)
|
|
|
```
|
|
|
|
|
|
Wrong:
|
|
|
```python
|
|
|
# Arguments on first line forbidden when not using vertical alignment.
|
|
|
|
|
|
foo = long_function_name(var_one, var_two,
|
|
|
|
|
|
var_three, var_four)
|
|
|
|
|
|
# Further indentation required as indentation is not distinguishable.
|
|
|
|
|
|
def long_function_name(
|
|
|
|
|
|
var_one, var_two, var_three,
|
|
|
|
|
|
var_four):
|
|
|
|
|
|
print(var_one)
|
|
|
```
|
|
|
|
... | ... | @@ -100,17 +86,14 @@ For flowing long blocks of text with fewer structural restrictions (docstrings o |
|
|
|
|
|
### A Line Should Break Before a Binary Operator?
|
|
|
|
|
|
`# easy to match operators with operands`
|
|
|
|
|
|
`income = (gross_wages`
|
|
|
|
|
|
` + taxable_interest`
|
|
|
|
|
|
` + (dividends - qualified_dividends)`
|
|
|
|
|
|
` - ira_deduction`
|
|
|
|
|
|
` - student_loan_interest)`
|
|
|
```python
|
|
|
# easy to match operators with operands
|
|
|
income = (gross_wages
|
|
|
+ taxable_interest
|
|
|
+ (dividends - qualified_dividends)
|
|
|
- ira_deduction
|
|
|
- student_loan_interest)
|
|
|
```
|
|
|
|
|
|
### Blank lines
|
|
|
|
... | ... | @@ -204,11 +187,11 @@ The documentation will follow the (numpy convention )\[<https://numpydoc.readthe |
|
|
|
|
|
A one-line summary that does not use variable names or the function name, e.g.
|
|
|
|
|
|
`def add(a, b):`
|
|
|
|
|
|
` """The sum of two numbers.`
|
|
|
|
|
|
` """`
|
|
|
```python
|
|
|
def add(a, b):
|
|
|
"""The sum of two numbers.
|
|
|
"""
|
|
|
```
|
|
|
|
|
|
#### Extended Summary
|
|
|
|
... | ... | @@ -218,37 +201,29 @@ A few sentences giving an extended description. This section should be used to c |
|
|
|
|
|
Description of the function arguments, keywords and their respective types.
|
|
|
|
|
|
`Parameters`
|
|
|
|
|
|
`----------`
|
|
|
|
|
|
`x : type`
|
|
|
|
|
|
` Description of parameter x.`
|
|
|
|
|
|
`y`
|
|
|
|
|
|
` Description of parameter y (with type not specified).`
|
|
|
```python
|
|
|
Parameters
|
|
|
----------
|
|
|
x : type
|
|
|
Description of parameter x.
|
|
|
y
|
|
|
Description of parameter y (with type not specified).
|
|
|
```
|
|
|
|
|
|
Enclose variables in single backticks. The colon must be preceded by a space, or omitted if the type is absent.
|
|
|
|
|
|
For the parameter types, be as precise as possible. Below are a few examples of parameters and their types.
|
|
|
|
|
|
`Parameters`
|
|
|
|
|
|
`----------`
|
|
|
|
|
|
`filename : str`
|
|
|
|
|
|
`copy : bool`
|
|
|
|
|
|
`dtype : data-type`
|
|
|
|
|
|
`iterable : iterable object`
|
|
|
|
|
|
`shape : int or tuple of int`
|
|
|
|
|
|
`files : list of str`
|
|
|
```python
|
|
|
Parameters
|
|
|
----------
|
|
|
filename : str
|
|
|
copy : bool
|
|
|
dtype : data-type
|
|
|
iterable : iterable object
|
|
|
shape : int or tuple of int
|
|
|
files : list of str
|
|
|
```
|
|
|
|
|
|
If it is not necessary to specify a keyword argument, use optional :
|
|
|
|
... | ... | @@ -258,25 +233,23 @@ If it is not necessary to specify a keyword argument, use optional : |
|
|
|
|
|
Explanation of the returned values and their types. Similar to the [<span dir="">Parameters</span>](https://numpydoc.readthedocs.io/en/latest/format.html#params) section, except the name of each return value is optional. The type of each return value is always required:
|
|
|
|
|
|
`Returns`
|
|
|
|
|
|
`-------`
|
|
|
|
|
|
`int`
|
|
|
|
|
|
` Description of anonymous integer return value.`
|
|
|
```python
|
|
|
Returns
|
|
|
-------
|
|
|
int
|
|
|
Description of anonymous integer return value.
|
|
|
```
|
|
|
|
|
|
#### Yields
|
|
|
|
|
|
Explanation of the yielded values and their types. This is relevant to generators only. Similar to the [<span dir="">Returns</span>](https://numpydoc.readthedocs.io/en/latest/format.html#returns) section in that the name of each value is optional, but the type of each value is always required:
|
|
|
|
|
|
`Yields`
|
|
|
|
|
|
`------`
|
|
|
|
|
|
`int`
|
|
|
|
|
|
` Description of the anonymous integer return value.`
|
|
|
```python
|
|
|
Yields
|
|
|
------
|
|
|
int
|
|
|
Description of the anonymous integer return value.
|
|
|
```
|
|
|
|
|
|
####
|
|
|
|
... | ... | @@ -284,19 +257,20 @@ Explanation of the yielded values and their types. This is relevant to generator |
|
|
|
|
|
An optional section that provides additional information about the code, possibly including a discussion of the algorithm.
|
|
|
|
|
|
`Notes`
|
|
|
|
|
|
`-----`
|
|
|
|
|
|
`The FFT is a fast implementation of the discrete Fourier transform`
|
|
|
```python
|
|
|
Notes
|
|
|
-----
|
|
|
The FFT is a fast implementation of the discrete Fourier transform
|
|
|
```
|
|
|
|
|
|
#### Hinting
|
|
|
|
|
|
All function parameters and returned values types should be hinted :
|
|
|
|
|
|
`def greeting(name: str) -> str:`
|
|
|
|
|
|
` return 'Hello ' + name`
|
|
|
```python
|
|
|
def greeting(name: str) -> str:
|
|
|
return 'Hello ' + name
|
|
|
```
|
|
|
|
|
|
### Documenting classes
|
|
|
|
... | ... | @@ -304,17 +278,14 @@ Use the same sections as outlined above (all except Returns are applicable). The |
|
|
|
|
|
An Attributes section, located below the Parameters section, may be used to describe non-method attributes of the class:
|
|
|
|
|
|
`An AtAttributes`
|
|
|
|
|
|
`----------`
|
|
|
|
|
|
`x : float`
|
|
|
|
|
|
` The X coordinate.`
|
|
|
|
|
|
`y : float`
|
|
|
|
|
|
` The Y coordinate.`
|
|
|
```python
|
|
|
Attributes
|
|
|
----------
|
|
|
x : float
|
|
|
The X coordinate.
|
|
|
y : float
|
|
|
The Y coordinate.
|
|
|
```
|
|
|
|
|
|
## Naming Conventions
|
|
|
|
... | ... | |