Is there a reason to write a comment at the beginning inside the function?

FAQ Python FAQ
#1

Question

Is there a reason to write a comment at the beginning inside the function?

Answer

Yes! Not only does it help you and other people who read your code understand what’s going on, but it also serves a more practical purpose: documentation. If you were to publish a library for others to be able to use, like the datetime library we used earlier, and someone wanted to know how to use a method belonging to your library, they could type help(function_name) into their Python interpreter and, if your function has this standard documentation, it will be displayed to them to help them understand how to use your awesome code!
For an in-depth look at this standard, take a look at the PEP docstring style guide.

4 Likes
FAQ: Learn Python: Functions - Function Junction
#2

It purely depends on you whether you want to write a comment at the beginning of a function. But adding a comment to your code make it much readable and simpler for you to understand in future reference . A code with a comment give a good impression of your coding Style . If your code lacks a comment it would be very difficult for another person to understand the code and gives an impression of a messy style . It will also help you a lot when you are writing a long code such as back end framework of a website where we write 1000s lines of code

6 Likes
#3

Is there a reason why we don’t use # here?

7 Likes
#4

The Python interpreter gives special status to a comment that is between triple quotes and that is the first item after def in a function definition.

If you are running a module or script whose functions contain those comments - called docstrings - then at your console, you can call

help(function_name)

… and the docstring will be printed to the screen.

(You can also incorporate some (primitive) testing capability in the docstring.)

(Comment, two hours later: I just noticed that box-in-box thing. It is a by-product of trying to type and edit the comment on my phone; I have no idea how I did it. Pretty cool, though!)

6 Likes
#5

The box-in-box-thing is markdown interpreting the python prompt. >>>

>>> def foo(x):
    '''
    a function to return x
    '''
    return x

>>> print (foo.__doc__)

    a function to return x

>>>
3 Likes
#6

Ah, and I just thought it was due to clumsy fingers!

1 Like
#7

Wow I’ve never heard of docstrings before. That’s very helpful to learn. Many thanks!

1 Like
#8

Is it compulsory to add a comment when defining a function?

#9

Not compulsory, no, although it does help to give a function a docstring that can be read with the help() builtin function.

def add(a, b):
    """
    a function that takes two inputs and returns their sum
    """
    return a + b

>>> help(add)
a function that takes two inputs and returns their sum
>>>
2 Likes
#10

Hello. im having trouble.

take a look at thisa a see what has happend.

Define your spam function starting on line 5. You

can leave the code on line 10 alone for now–we’ll

explain it soon!

def spam():

“”“Prints ‘Eggs!’”""

print “Eggs!”

Define the spam function above this line.

spam()

Its not working!

#11

Please see the following- How do I format code in my posts? and format your code as it’s not clear how your function is set up at the moment. If this is for a specific lessons then please link it too.