8

How come python reacts to indentations of a comment?

def foo():
    """
    Random comment
    """
    return True

works, but:

def foo():
"""
Random comment
"""
    return True

doesn't work, throwing an IndentationError.

Seems weird to me since comments shouldn't be nothing more then comments. And by the way, this works:

def foo():
# Another random comment
    return True
Martijn Pieters
  • 1,048,767
  • 296
  • 4,058
  • 3,343
SlimJim
  • 2,264
  • 2
  • 22
  • 25

2 Answers2

14

The tripple-quoted string is not a comment; it is the docstring of the method. You can access it with foo.__doc__ later, for example, or have it formatted for you with help(foo). Tripple-quoting (""" or ''') is a python-specific method of specifying a string literal where newlines do not need to be escaped.

As such, it is part of the body of the function, and thus needs to be indented to match. In fact, any string appearing as the first statement of a function is treated as a docstring, single quoting would work too. The same trick works for classes and modules too.

A lot of tools can make use of this documentation string; you can embed doctest tests in this information, for example. See PEP 257 for conventions on formatting this string.

Comments on the other hand, are always denoted by a # (where not part of a string literal) and are ignored up to the end of a line. If all the line contains is a comment, the whole line is thus ignored, as would a line with only whitespace. See the documentation on comments.

Martijn Pieters
  • 1,048,767
  • 296
  • 4,058
  • 3,343
  • 2
    You should add that comments in Python only start with `#` and nothing else. – Burhan Khalid Aug 08 '12 at 08:01
  • 1
    I believe you are overemphasizing the docstring-ness. The indentation issue has nothing to do with docstrings per se. It just has to do with strings. – BrenBarn Aug 08 '12 at 08:01
  • with `pep 257` you have to read comments section from `pep8` http://www.python.org/dev/peps/pep-0008/#comments – Dmitry Zagorulkin Aug 08 '12 at 08:03
  • 1
    @BrenBarn: Education about docstrings is just as important here; recognition that the first string literal is not a comment is the main point, as the OP clearly knows about the `#` syntax. – Martijn Pieters Aug 08 '12 at 08:07
  • @MartijnPieters: Your answer only applies if the string literal is the first thing in the block, but from the OP's phrasing it appears likely he thinks *all* triple-quoted strings are comments, which is why I think it's broader than just docstrings. – BrenBarn Aug 08 '12 at 08:09
3

The triple-quoted string is not a comment, it is a string literal. It's not assigned or used in any way by your code, but it's still a regular string and has to fit the syntax of Python. (In this case it happens to be the docstring, but that has nothing to do with whether indentation matters for it or not.)

# is the way to get comments.

BrenBarn
  • 242,874
  • 37
  • 412
  • 384
  • 1
    @Martijn Peters: I assume you mean it's the docstring? It's not assigned or used in the code. It happens to be the docstring, but that has nothing to do with why indentation is or isn't required. I edited to clarify that it is the docstring, though. – BrenBarn Aug 08 '12 at 07:57
  • 1
    Not assigned or used *in his examples here*, but it *is* assigned! Your statement is at best confusing. – Martijn Pieters Aug 08 '12 at 08:08
  • @MartijnPieters What is it [assigned](http://docs.python.org/reference/simple_stmts.html#assignment-statements) to? And quoting BrenBarn in full, what is it "assigned to by your *[the OP's]* code"? – anton.burger Aug 08 '12 at 08:12
  • 3
    @shambulator: the interpreter assigns it to the `.__doc__` attribute of the function, class or module. No explicit assigment operator is required, although `foo.__doc__ = 'your new docstring'` works just fine. – Martijn Pieters Aug 08 '12 at 08:16