Coding Conventions¶

Below is list of coding conventions agreed upon by Nathan and I(Grant). Please adhere to these conventions to create a more readable codebase.

Column Width

Code should be no longer than 100 characters, in the case your statement goes over, use a new line or split your statement up.

String Literals

String Literals are denoated with '', docstring should be double quotes ""

var = 'Heres a string'
def foo():
"""
Heres a docstring
"""
    pass

Variables

Variables should be lowercase and word separated with _

var = 3
another_var = 4
more_words_than_previous_var = 5

Functions

The same format as Variables, lowercase with _ separating words should be used.

def func():
   # ...
def adheres_to_coding_convention_func():
   # ...

Classes

Uppercase CamelCase should be used to repesent classes.

class Shape(object):

class SquareObject(Shape):

Tabs

Currently should use spaces as opposed to tabs.:

var = [1,2,3,4,5]
for v in var:
    print v        # 4 space indent

General Rules

No spaces should be left between conditional statements and loops code blocks.

if x is not y:
   # ...

for x in y:
   # ...

Simple comments should be placed to the right of the line when possible, or one comment should be placed above a segment shortly explaning it’s function

var = x - y + r*2           # calculate ___ and place in var
doFunc(var)                 # do some func with var param
if var[-1] is not var[:3]:
   err()                   # error is var does not match criteria

# does this and this and this
var = x + 2
x = var - 5
if var == 0:
   err()

This documentation website is generated using docstrings from source, so document as you code! The docstring markdown is reStructedText Primer and sphinx, when the doc chain is generated it will use these docstrings from the code for the webpage.

class Foo(object):
"""
Class description is placed here

:param <name>: description of param 'name'
"""

   def __init__(self, name):
      #...

   def foo(self, x, y)
   """
   Description of function here

   :param int x: parameter x is an integer and does ....
   :param int y: parameter y is an integer and does ....
   :rtype: returns int
   """

The auto documentation tool chain will generate this as:

class Foo

Class description is placed here

Parameters:	name – description of param ‘name’

foo(self, x, y)

Description of function here

Parameters:	x (int) – parameter x is an integer and does... y (int) – parameter y is an integer and does...
Return type:	returns int

If you are developing in an existing file , the doc chain should find your new function/class automatically. In the case you are creating a new module, determine whether it is in the general, polygon or tools package, and create a .rst file in the corresponding doc/ folder specifying your new module. You can refer to the exisiting .rst files for how to populate the docs. You can also refer to the Documentation Page for writing your own docs.