Skip to content

Latest commit

 

History

History
113 lines (96 loc) · 4.07 KB

coding_guidelines.md

File metadata and controls

113 lines (96 loc) · 4.07 KB
Raw

Coding guidelines for OCS-CI project

Lets follow the following guidelines for the Core Libraries and Test Scripts

  • Follow pep8 or use autopep8 to automagically conform to pep8 style.
  • Each Python Class is well documented for inheritance, methods and attributes. Add sufficient comments for code block that is easy to understand for others to review. Use Google Style of Python Docstrings
  • Code Readability takes priority, Lets avoid crazy hacks and tricks and stick to straight forward code blocks that are easy to understand for all.
  • For core libraries when possible please add the unittest to minimize regression for many tests
  • Helper functions that are useful to wide variety of tests should reside in utils and/or should be carefully reviewed to check if they can actually be methods.
  • test_scripts will reside in test/ folders and will define run function
  • test_scripts should return non zero exit status for failure and 0 for 'pass'. The recommended way is to directly return the TestStatus from Enum TestStatus which you can import from enums module. We are trying to transform int Unix RC to TestStatus automatically.

ex: test_scripts/test_ocs_operator.py

        def run(ocs_context, **kw):
            # use ocs_context to deal with cluster
            # run your test steps
            if test_failed:
                return TestStatus.FAILED
            else:
                return TestStatus.PASSED
  • Do not use backslashes in the code for line breaker!
  • Line length should be maximum 79 characters!
  • Try to follow this convention for brackets and indentions like in example below if the line doesn't fit in 79 chars! (This makes code much more readable):
def function(
    parameter1, parameter2, parameter3, parameter4, parameter5, parameter6,
    parameter7='Default value of param7'
):
    print(
        "Hello, I am long string which can be easily split like this"
        "without using backslashes!"
    )
    my_dict = {
        'key1': "Value is long and it looks better to have new line here",
        'another_key': 'Another value',  # please keep comma at the end!
    }
    if value >= 10:
        print("Doing something here")
        my_list = [
            variable for variable in range(100) if variable % 2 == 0 if
            variable % 5 == 0
        ]

        # If line can fit in 79 chares do it as one liner (No need to split)!
        my_list_fit_one_line = [x for x in range(10)]
  • String formatting: use new style of string formatting:
print("These are new style of Python formatting:")
"My string {}".format("value")
"My string {var_name}".format(var_name="value")
f"This is the best and preferred way {var_name}"  # from Python 3.6

print("This is old style of formatting and should be avoided:")
"My string %s" % variable
  • Docstring:
  • Use capital letters properly
  • Every docstring should describing easily what the function/class/etc. do
  • The description should be as follow:
def my_example(arg1, arg2=10):
    """
    This function is for showing how a proper docstring should
    look like

    Args:
        arg1 (<type of argument>): Description of what this argument is and if
            the line is too long we will indent according to this (4 spaces)
        arg2 (int): This argument is an integer (default: 10)

    Raises:
        ExampleException: you get it

    Returns:
        bool: description of when returns False and when True.
            But this can also return anything else like int, str, list, etc.
    """
    pass
  • Logging: let the logger format log message for you:
logger.info("My message %s", variable)  # No usage of % after string!
# This is still under consideration. We can set the style of logger
# format to use {} instead %s which is possible from Python 3.2.

Here is the Python documentation for Logger Styles.