If you don't follow the PEP8 rules, your dog will bark !?

In python, there is a style guide and coding standard called PEP8. In the case of a team, by checking the code to see if it meets the PEP8 convention, it will be aligned in a common writing style, making it more readable and easier to develop. You can check PEP8 when you push to github etc. or when you make a pull request. At that stage, CI tools are used to test and notify you of any points that violate the rules. One such tool is reviewdog. ファイル名

If you act against the PEP8 rules, you will be barked by this dog. .. ファイル名

I was told that the dog kept barking at the errors H404 and H405 related to the docstring, and I tried my best to fix the code and let the dog forgive me.

Contents of error code H4xx

H4xx series error codes are related to ** docstring **. A docstring is a place to describe a function or class method when you create it. By the way, this looks good docstring, which makes dogs bark! !! (Not fully compliant with PEP8)

def docstring_sample(hoge1: str):
    """ 
This is the docstring.

If there is an argument, it will be explained here. (There are some templates, so check them out.)
This time in numpy style

    Parameters
    ----------
        hoge1 : str
Output the character string entered here"""
    print(hoge1)

There are other error codes for many things [here](https://blog.sideci.com/about-style-guide-of-python-and-linter-tool-pep8-pyflakes-flake8-haking-pyling -7fdbe163079d) is nicely organized!

Let's take a look at the contents of 4xx!

[H401] Docstrings should not start with a space.
[H403] Multi line docstrings should end on a new line.
[H404] Multi line docstrings should start without a leading new line.
[H405] Multi line docstrings should start with a one line summary followed

I'm not good at English, so I had a hard time understanding H404 and H405 ... I will translate it (it is a free translation)

-[H401] Do not start the description of Docstrings with a space. -[H403] When writing a multi-line docstring, start a new line on the last line and then close it. -[H404] When writing a multi-line docstring, leave one line first and then write. -[H405] When writing a multi-line docstring, write a summary of the function on one line before you start writing.

about it.

When I read this, I "I see, that means that in the previous sample, there was no line break at the end, and there was no space at the beginning, so let's rewrite it." Does that mean something like this?

def docstring_sample(hoge1: str):
    """ 

A function that outputs the argument hoge1. (Because I was told to write a summary at first)
This is the docstring.

If there is an argument, it will be explained here. (There are some templates, so check them out.)
This time in numpy style

    Parameters
    ----------
        hoge1 : str
Output the character string entered here
    """
    print(hoge1)

However, this makes the dog bark **. The error code is H405. Why. .. So I melted it for a few hours. (For me, it's a rule that you can't merge into master as long as the dog barks ...)

approach

After a few hours of doing various things, the dog finally recognized me! !! that is

Write H405 at the very beginning of the docstring!

In other words, write a summary before breaking a line-> break a line.

Finally, we have a docstring that complies with the PEP8 convention!

def docstring_sample(hoge1: str):
    """A function that outputs the argument hoge1.
    
This is the docstring.
If there is an argument, it will be explained here. (There are some templates, so check them out.)
This time in numpy style

    Parameters
    ----------
        hoge1 : str
Output the character string entered here
    """
    print(hoge1)

By the way, if you write only one line of docstring, you don't have to break the " "" at the end of the sentence.

def docstring_sample(hoge1:str):
    """Function that outputs the argument hoge1"""
    print(hoge1)

Summary

In PEP8, you can ignore this as expected, right? I think there are several. (Limitation on the number of characters in one line) However, if you control yourself and write it in a lawful manner, it will give you a sense of accomplishment! Please try it!

Below are some references! I also refer to the numpy style and always use it! Thank you for being so easy to understand!

References

https://blog.sideci.com/about-style-guide-of-python-and-linter-tool-pep8-pyflakes-flake8-haking-pyling-7fdbe163079d

[Python] Learn how to write a docstring to improve readability (NumPy style)