[pythonvis] Few comments on writing comments in Python
- From: "Joseph Lee" <joseph.lee22590@xxxxxxxxx>
- To: <pythonvis@xxxxxxxxxxxxx>
- Date: Mon, 5 May 2014 12:04:41 -0700
Hi all,
One of the questions asked on the audio session today was how to write
comments. Here are some comments on comments:
There are two styles of comments: one-liners and docstrings. One-liners are
the ones beginning with a hash (number sign or pound, #). For example:
# This is a comment.
The Python interpreter will ignore this line. You can also write something
like this:
If someCondition: # Do something
This is also valid, as the interpreter will look at the conditionals and
will ignore the comment.
These one-liners are used in various contexts. To some, it is used to
explain what the following lines will do, others use it at the beginning of
method bodies to explain what the method does.
As opposed to one-liners, some use docstrings. These have the form:
"""Some documentation string.
These can span multiple lines."""
(Note: some of you may see this as left/right quotes.)
Again, just like one-liners, docstrings are used in various places. It is
commonly used to write documentation for a class or a module, others use it
to explain function syntax and so on.
For C/C++ family speakers, these two styles are equivalent to:
// One liner = #.
/* documentation
*/ = """ documentation """
I'd advise starting out with one-liners as you learn Python. Also, it is a
good practice to write a header comment (some one-liners) at the top of the
file describing what the file is about (some professional projects do ask
that developers write these).
Thanks.
Cheers,
Joseph
Other related posts:
- » [pythonvis] Few comments on writing comments in Python - Joseph Lee
