Docstring

# Docstring Best Practices
# ========================
# - Enclose docstrings in triple quotes
# - First line should be summary sentence of functionality
# - Modules: List important classes, functions, exceptions
# - Classes: List important methods
# - Functions:
#   = List parameters and explain each, one per line
#   = If there's a return value list it, otherwise omit
#   = If the function raises exceptions, mention those

# Documentation strings
def myFunc(arg1, arg2=None):
    """myFunc(arg1, arg2=None) --> Doesn't really do anything.
    Parameters:
    arg1: the first argument. Whatever you feel like passing
    arg2: the second argument. Defaults to None. Do whatg you like
    """
    print(arg1, arg2)

def main():
    print(myFunc.__doc__)

if __name__ == "__main__":
    main()

# Output:
myFunc(arg1, arg2=None) --> Doesn't really do anything.
Parameters:
arg1: the first argument. Whatever you feel like passing
arg2: the second argument. Defaults to None. Do whatg you like

 

# Reasons to Document your Code
# =============================
# Documenting your functions (and classes) makes it much wasier
# for other people to use them.
#   - Without documentation, other programmers will have to guess what your functions do,
#   and how to call them.
#   - If guessing is too much work, they won't use your functions. If they have to waste time
#   writing the same functions again, you'll get fired and your children wil starve.

# That "other programmer" might be you, months or years later.
#   - Remember that your code could be in use for years.
#   - Documentation will help you to understand your code, when you come to
#   modify it later.

# If you write the documentation for your functions, before you write the code,
#   you'll have a clear idea of what the function's going to do.
#   - You'll have described any parameters, and the return values (if there are any), and
#   what the function is supposed to do.
#   - This is the reason that might not have been obvious.
#   - If you start writing code with a clear idea of what that code has to achieve, you're
#   far more likely to produce something that works.