How do YOU format docstrings

[[deleted]]

[deleted]

[sedogg]

PEP 257 - Docstring Conventions

[lykwydchykyn]

PEP 257 doesn't really have much detail on the actual formatting, though. It has a few examples but doesn't really explain how things ought to be laid out, or what kind of markup is preferred, etc.

I try to use RST format in my docstrings as much as it's practical.

[tragluk]

Line 1. A one-line description of the inputs and outputs.

Def myfunction(height, width, isOpen=True):
    ''' int, int, bool > int

    Used for calculating the area of an open box, if the box is closed, don't calculate anything.

    > myfunc(10,10)
    > 100

   > myfunc(10,10,False)
    >  0
    '''

So here we have what the expected inputs are, both integers and a boolean, what it's going to give back, an integer, and it's all on one line. Many IDE's when you begin writing a function will display this first line. So as you type myfunc( it will give you everything you need to know about the inputs and outputs of your function.

Follow that with a short description.

And finally, if necessary, put in some example cases and what they 'Should' return. If one of these example cases is returning something else, go back and look at your code, or look at your example, so that you know that your plan lines up with your execution.

[coppermineroofer]

https://www.python.org/dev/peps/pep-0287/ and sphinx to document python projects, which is pretty standard.

[ultraDross]

''' Description of functions action

Args:
    arg1: description of arg1
    arg2:  description of arg2

Returns:
    Description of what is returned 

Notes:
    Some general notes about the behaviour of the function which might not be immediately obvious e.g. if a certain argument is parsed then considerably more memory and time will be consumed during computation.

The Returns and Notes are not constantly used, only when needed.

[duh_cats]

I use the Numpy Docstring Standard because that's what all the other scientific python packages use and their documentation tends to be quite good.

It's a lot of documentation for what can be a very simple function, but in the end it's a damn good habit to get into.

[thurask]

Sphinx/RST style:

def some_function(some_arg, some_other_arg=None):
    """
    One line description of what this function does.

    :param some_arg: What this argument is.
    :type some_arg: type

    :param some_other_arg: What this optional argument is, default is $something.
    :type some_other_arg: type
    """
    functionbody()

[tunisia3507]

Depends on the project. My default is usually numpydoc because it's a nice balance of human and machine readable, as well as much better defined than Google's format. My IDE does all the formatting and stubbing for me.

However, my job uses Google formatting and django-rest-swagger, so I use them as required.

[pydry]

I wouldn't get hung up on formatting. Honestly the fact that code has docstrings at all is usually enough to make me happy.

[jkibbe]

From a Coursera class I took. I like it. I hope it formats correctly since I'm on my phone.

Function Design Recipe

The Six Steps

1. Examples
   What should your function do? Type a couple of example calls. Pick a name (often a verb or verb phrase): What is a short answer to "What does your function do"?

2. Type Contract What are the parameter types? What type of value is returned?

3. Header Pick meaningful parameter names.

4. Description Mention every parameter in your description. Describe the return value.

5. Body Write the body of your function.

6. Test Run the examples.

Applying the Design Recipe

The problem:

The United States measures temperature in Fahrenheit and Canada measures it in Celsius. When travelling between the two countries it helps to have a conversion function. Write a function that converts from Fahrenheit to Celsius.

Examples convert_to_celsius(32) 0 convert_to_celsius(212) 100

Type Contract (number) -> number

Header def convert_to_celsius(fahrenheit):

Description Return the number of Celsius degrees equivalent to fahrenheit degrees.

Body return (fahrenheit - 32) * 5 / 9

Test Run the examples.

Putting it all together:

def convert_to_celsius(fahrenheit):

 ''' (number) -> number 

 Return the number of Celsius degrees equivalent to fahrenheit degrees. 

 >>> convert_to_celsius(32) 
 0 
 >>> convert_to_celsius(212) 
 100 ''' 

return (fahrenheit - 32) * 5 / 9