Python comments vs. docstrings: What, how, and why

REUVEN LERNER: Hey there, Python
trainer Reuven Lerner here.

And I got a question
from Roger, a subscriber

to my Better Developers
mailing list, and he asks,

what's the difference between
comments and docstrings?

What are the similarities
and differences between them?

So let's talk about
this a little bit.

Let's talk first about comments.

And we'll talk about docstrings,
and then we'll compare them.

So if I write Python code, x
equals 100, def hello name,

return--

this is hello name.

In all these cases,
what's happening?

Well, I want the
code to execute.

The code is meant for
Python to actually do

something-- in the first
case to define a variable x

and assign it 100,
and the second case

to define a function.

And here I can then
say hello world.

And now I want it to
actually run that function.

In all these cases,
Python takes whatever I

wrote, turns it into bytecodes.

It actually compiles my code
into internal bytecodes,

and then it runs
those bytecodes.

In the case of the function,
it holds on to those bytecodes

later on.

Now it is absolutely, positively
true that when you write code,

you should be thinking about the
people who will be reading it

later on and
maintaining it later on

because it's much, much
easier to write code

than to maintain code.

So that readability--
very important.

So use long variable names,
use long function names.

But sometimes we need to give
a little bit of an assistance.

It's not enough to
just write clear code.

We sometimes need to tell
people what we're doing

and, more importantly,
why we're doing it.

And for that, we have comments.

So I can write a comment.

And in Python, a
comment is hashmark

until the end of the line.

So this is a friendly function.

All right.

That's a very, very
useless comment.

Why?

It doesn't give
us any information

we could use about in order
to maintain the function.

But it is a comment.

It's legitimately a comment.

And how does Python
see a comment?

That's the thing.

Python doesn't.

It completely and
utterly ignores them.

When we turn our
functions into bytecodes,

the comments are thrown away.

They are only for
the maintainers

and to make our code easier to
understand, easier to maintain.

So what should you be
writing in your comments,

and who are your
comments aimed for?

Your comments are
aimed for the people,

aimed at the people
who are going

to be maintaining the function.

In this case, maintaining your
module, maintain your code.

It's like the-- not the
owner's manual for a car.

Rather, it's like
the manual that

is for the people who will be
fixing your car, who really need

to understand the internals.

So what exactly-- what would
I do here, for example?

Well, maybe I would explain
why I'm doing something.

Don't say something like return
a string with the user's name.

That is really, really useless.

That's not going to
help anyone at all.

We can already see that
we've got an f string.

We already see that
we've got the name there.

But we can say here
something like return

a string instead of printing
it for greater flexibility.

Now, that's still not
a fantastic comment,

but at least it gives an insight
into the thinking what we're

planning to do, thinking to do.

And so it gives some better
sense of why we wrote it

the way we did.

And of course, there are
lots of places in code,

especially older code, where
you'll see things like,

don't touch this unless
you know what you're doing,

or something like,
here be dragons.

You don't want to do that,
but people do it all the time.

OK, so that's comments.

And you should comment,
I think, as little as

possible because I found that
people use comments as a crutch.

I found that when you use
comments in your code,

you're less likely to use
good variable, good function

names, good other things
to make your code readable.

But should you use comments?

Yeah.

No comments is, I think, a
little extreme and unnecessary.

So definitely include comments.

Now, some people
complain that you

can't have comments that
stretch over one line, more

than one line.

If I have here comment 1,
comment 2, and comment 3--

yeah, well, that's
annoying, but that's just

the way it is-- you
could, in theory, use

a triple-quoted string to
go across several lines.

I really dislike that, but I
know that many people do it.

OK, so those are comments.

So comment only on why not what.

Comment less rather
than more in order

to force yourself to
write clearer code,

and write the comments
that are aimed

for the maintainers of the code.

So what's a docstring then?

Well, let's take
our function here.

Hello.

And if I define my
function-- and I'm

not quite sure how to use it.

So I'm going to say
here help on hello.

And I hear that--

I find out from
running help on it.

It's a function, and
it takes one argument.

And the parameter
is called name,

but I don't know
much else about it.

So this is where a
docstring comes in.

A docstring is a
documentation string.

It is only there
if you define it.

So you actually need to do this.

It's traditionally a
triple-quoted string,

and it is aimed at the people
who will be using your function,

not the people who will be
maintaining your function.

Big difference.

Imagine you, the
owner of your car,

versus the garage that
fixes your car-- not

the same audience.

So the comments can go into
deeper technical detail.

The docstring really should be,
how do you use this function?

What does it do?

So returns a string with
a friendly greeting.

Now back when I was taking
software engineering

in my university days,
a long, long time ago,

our professor told us that
documentation for the user

API docs should
include three things--

what does it expect, expects--

or I should say, yeah, expects--

and modifies and returns.

And it turns out
this combination

is great to have in
the documentation.

So what does this expect?

Expects a string.

Was it modified?

Nothing.

And what does it return?

A string with a greeting.

Now this is again,
pretty bare-bones--

but it's a pretty
bare-bones function.

So how much documentation
do we really need?

Notice once again is a triple
quoted string, even if it's only

going to be one line
long, but you'll typically

want to write more than that.

After I've written
this function,

now comments were thrown
out by the byte compiler,

but the docstring is
actually kept around.

It's kept around in dunder
doc on our function object.

See, it was just like
grabbed and put over there.

And if I run my function,
no difference whatsoever.

But if I say now
help on the function,

help on hello, we
will get our help,

and we'll find out
how we should run it

and what we should do with it.

If you, of course, want, you
can put in additional stuff

in the docstring.

And they're docstrings
for classes and docstrings

for modules as well.

And most of the code checkers,
like Pylint and PyFlakes,

will actually ding
you a little bit

and scold you if you
don't include a docstring.

So make sure to
include docstrings

on all of your functions,
modules, and classes.

I hope that was a good
introduction to docstrings

versus comments.

I hope that you will
indeed comment your code,

and you should also join
my Better Developers list.

It's at
betterdevelopersweekly.com.

Send me questions,
send me comments.

I'd love to hear from
people around the world,

and I'll be back soon with
more videos and explanations.