<jupyter_start><jupyter_text>Comments and documentation  Commenting code- Confirm comment character if haven't seen it already (unlikely)- Purpose of comments- Where/why/how to write comments- cat/dog picture- go back through code and make sure it's commented  Documentation- Broad concept of why there should be docs (large scale)- smaller scale reasons for having docs- docstrings, etc- go back through code and doc it- see docstring challenges in swc function material  Documenting codeNow that we've started thinking about re-using parts of our code, we need to think about what that will actually involve for the user. At the moment, the user is yourself, and you've only just written the function, so it doesn't take a lot to remember what the function does and what parameters it takes.But re-using code doesn't just mean within a single project in the short term. You might have some task you want to do many times over several projects over the next few years, in which case the user may be future-you. Will you remember in two weeks' time what parameters your function takes? How about in two months? Two years? If you make your code available to others to use, they will also want to know how to use your functions.One way of figuring out how to use a function is to simply look at the code, but this isn't ideal. It means finding the particular file where the function is written and looking through the whole function to see what all the variables do, which is time-consuming and can be difficult in large or complex functions. A much better solution is documentation - writing down what your code does as you write it.Some large software packages may have a manual, or narrative documentation which describes conceptually how and why to use different parts of that software. These are useful and an important aspect of documentation. But for now we'll focus more on documenting the code itself, which is more likely to be helpful when working on a smaller or personal project. To do this we'll use two things: comments, which we've already seen, and **docstrings**.For this lesson we'll use a new function to demonstrate documentation. It will take a NumPy array and shift it such that the mean is offset to some user-defined value.<jupyter_code>import numpy as np

def offset_mean(data, target_mean_value):
    return(data-np.mean(data)) + target_mean_value<jupyter_output><empty_output><jupyter_text>Comments - reminderComments are lines in a code which are ignored when the code is run. They're usually indicated by a comment character at the start of the line (in Python's case, a hash, ''), and they're a crucial part of documenting code.  How not to use comments![](https://matrix.org/_matrix/media/v1/download/cadair.com/JtaDnstvdkcNHasPpOzqzOSr)Comments are important but they have to be carefully considered. This picture demonstrates a common way in which comments are misused, by simply describing exactly what the corresponding code does. For the function we wrote above, such a comment might look something like this:<jupyter_code>MEow<jupyter_output><empty_output>
{'fraction_non_alphanumeric': 0.04301423027166882, 'fraction_numerical': 0.0003234152652005175, 'mean_word_length': 4.803001876172608, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '2', 'dir': 'jupyter-structured-clean-dedup', 'id': '302804', 'license': 'CC-BY-4.0', 'n_tokens_mistral': 744, 'n_tokens_neox': 714, 'n_words': 470, 'path': '03-fundamentals-of-python/07-comments-and-docs.ipynb', 'repo_name': 'D-DePablos/rcsc18_lessons', 'size': '3092'}