<jupyter_start><jupyter_text>8 Help and documenting Python can be overwhelming, especially when you are reading someone else's scripts.There are two ways to make this simpler:    1. Comments on scripts2. Use the help module  8.1 Line Comments As previously mentioned, comments are simple to introduce within code. Using `` in a line makes the rest of the line a comment. The interpreter will simply skip anything after the `` when processing your code. This means you can annotate all the little details of your code to help others follow it better (and yourself, too!).<jupyter_code># Define list x
x = [1, 2, 3]

# Print list x
print(x)<jupyter_output><empty_output><jupyter_text>Unfortunately, too many comments can also be confusing; a good way to avoid many comments is to give a sensible name to your variables and functions. The following code is not very clear and therefore it has to be commented:<jupyter_code>m = 1 # Mass
a = 3 # Acceleration

# Compute force f
f = m * a<jupyter_output><empty_output><jupyter_text>By choosing better names for our variables we can completely avoid comments without losing clarity:<jupyter_code>mass = 1
acceleration = 3

force = mass * acceleration<jupyter_output><empty_output><jupyter_text>8.2 Multi-Line Comments A multi-line string can be used as a comment:<jupyter_code>"""
Very long
and multi-line
comment
"""

print("The previous comment is ignored.")<jupyter_output><empty_output><jupyter_text>8.3 Docstrings A multi-line comment used to document a function is called *docstring*:<jupyter_code>def force(mass, acceleration):
    """
    This function computes the force using Newton's first law.
    """
    return mass * acceleration<jupyter_output><empty_output><jupyter_text>Docstrings are extremely helpful to document functions, especially if other people need to use them. Luckily, all good Python packages use docstrings to document their functions!If you write any function, you are heavily encouraged to write docstrings for them.For a good example of how to write docstring, we refer you to the numpy docstring guide: https://numpydoc.readthedocs.io/en/latest/format.html  8.4 Help The help module can give a lot of information on how to use certain functions. You can pass a function the `help` to get some information:<jupyter_code>help(list)<jupyter_output><empty_output><jupyter_text>With the `help` function in hand, you can quickly look at the docstring for different functions. It's extremely clear why docstring are so important:<jupyter_code>help(force)<jupyter_output><empty_output><jupyter_text>If our function was not documented with a docstring, this would be the result:<jupyter_code>def f(m, a):
    return m * a

help(f)<jupyter_output><empty_output><jupyter_text>Not very informative, is it? In Jupyter Notebooks (or the [IPython](https://ipython.org/) console) you can also use `?` to obtain additional information interactively:<jupyter_code>force?<jupyter_output><empty_output>
{'fraction_non_alphanumeric': 0.07162162162162163, 'fraction_numerical': 0.006081081081081081, 'mean_word_length': 5.624161073825503, 'pattern_counts': {'":': 0, '<': 37, '<?xml version=': 0, '>': 37, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '9', 'dir': 'jupyter-structured-clean-dedup', 'id': '236872', 'license': 'BSD-3-Clause', 'n_tokens_mistral': 858, 'n_tokens_neox': 826, 'n_words': 362, 'path': 'tutorials/Python/08_Documentation/Documentation.ipynb', 'repo_name': 'AfroditiMariaZaki/OxCompBio', 'size': '2960'}