Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #87696

Re: A simple single line, triple-quoted comment is giving syntax error. Why?

Show all headers | View raw

Laurent Pointal wrote:

> Laurent Pointal wrote:
>> Take care of indent:
>> 
>> def f(x):
>>     a = 5
>>     """an correctly indented expression to be
>>     inside the function"""
>>     return a * x
> 
> Here only the first indent of """ at beginning of the string to be aligned
> to function bloc is important, remaining content of the string can be
> indented or not.

I must strongly object and recommend against getting accustomed to the 
suggested use of multi-line string literals.  First of all, it is too easy 
to produce invalid code this way.  Also, standalone multi-line string 
literals in Python code serve a specific purpose when at the beginning of a 
function, method or class clock: they constitute *docstrings”, setting the 
respective object’s “__doc__” attribute:

>>> def f(x):
...    """Returns a multiple of 5"""
...    a = 5
...    return a * x
... 
>>> print(f.__doc__)
Returns a multiple of 5

This means that different to real comments, the content of string literals 
is *parsed*.  You do not want to waste the time of the compiler compiling 
code that serves no purpose; particularly not in a language like Python 
where code is JIT-compiled by default.

Not any less important: Using standalone multi-line string literals in any 
other way is syntactically correct indeed, but makes the code harder to 
read.  Keep in mind that code may be written only once, but read many times 
by other people during its lifetime.  It is important to write code so that 
it is easy to read, so that it can be easily reused and adapted by oneself 
and others (a month, a year later).

If you want to comment your code, then by all means do so using docstrings 
and *real* comments.  IDEs like PyDev support you there.  That way also the 
syntax highlighting will be correct.  And with real comments, the Python 
compiler does not care about the indentation.  As to where you should put 
comments, I recommend in general, in all programming languages, if possible 
to put the comments on their own line, *before* the statement that they are 
describing, and using the same indentation, preferably preceded by an empty 
line (so that the comment and the code it documents stand out).

<https://docs.python.org/3/tutorial/controlflow.html#documentation-strings>
<https://docs.python.org/3/reference/lexical_analysis.html#line-structure>

-- 
PointedEars

Twitter: @PointedEars2
Please do not cc me. / Bitte keine Kopien per E-Mail.

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

A simple single line, triple-quoted comment is giving syntax error. Why? Aditya Raj Bhatt <adityarajbhatt@gmail.com> - 2015-03-18 10:46 -0700
  Re: A simple single line, triple-quoted comment is giving syntax error. Why? Laurent Pointal <laurent.pointal@laposte.net> - 2015-03-18 19:04 +0100
    Re: A simple single line, triple-quoted comment is giving syntax error. Why? Laurent Pointal <laurent.pointal@laposte.net> - 2015-03-18 19:06 +0100
      Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-18 20:53 +0100
        Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-18 20:56 +0100
        Re: A simple single line, triple-quoted comment is giving syntax error. Why? Terry Reedy <tjreedy@udel.edu> - 2015-03-18 17:47 -0400
        Re: A simple single line, triple-quoted comment is giving syntax error. Why? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2015-03-19 09:58 +1100
          Re: A simple single line, triple-quoted comment is giving syntax error. Why? Chris Angelico <rosuav@gmail.com> - 2015-03-19 10:23 +1100
    Re: A simple single line, triple-quoted comment is giving syntax error. Why? Aditya Raj Bhatt <adityarajbhatt@gmail.com> - 2015-03-18 11:23 -0700
      Re: A simple single line, triple-quoted comment is giving syntax error. Why? Igor Korot <ikorot01@gmail.com> - 2015-03-18 14:45 -0400
      Re: A simple single line, triple-quoted comment is giving syntax error. Why? Laurent Pointal <laurent.pointal@laposte.net> - 2015-03-18 20:08 +0100
      Re: A simple single line, triple-quoted comment is giving syntax error. Why? Tim Roberts <timr@probo.com> - 2015-03-28 16:34 -0700
  Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-18 21:21 +0100
  Re: A simple single line, triple-quoted comment is giving syntax error. Why? Tim Chase <python.list@tim.thechases.com> - 2015-03-18 13:15 -0500
  Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ben Finney <ben+python@benfinney.id.au> - 2015-03-19 11:06 +1100
  Re: A simple single line, triple-quoted comment is giving syntax error. Why? Denis McMahon <denismfmcmahon@gmail.com> - 2015-03-19 00:53 +0000
    Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-22 04:14 +0100
      Re: A simple single line, triple-quoted comment is giving syntax error. Why? Chris Angelico <rosuav@gmail.com> - 2015-03-22 14:36 +1100
        Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-22 04:49 +0100
          Re: A simple single line, triple-quoted comment is giving syntax error. Why? Chris Angelico <rosuav@gmail.com> - 2015-03-22 15:11 +1100
            Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-26 05:35 +0100
              Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ian Kelly <ian.g.kelly@gmail.com> - 2015-03-25 23:09 -0600
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-26 17:45 +0100
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ian Kelly <ian.g.kelly@gmail.com> - 2015-03-26 12:29 -0600
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-26 19:54 +0100
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ian Kelly <ian.g.kelly@gmail.com> - 2015-03-26 17:27 -0600
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-28 19:20 +0100
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ian Kelly <ian.g.kelly@gmail.com> - 2015-03-29 01:56 -0600
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-29 12:41 +0200
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ian Kelly <ian.g.kelly@gmail.com> - 2015-03-31 01:23 -0600
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? sohcahtoa82@gmail.com - 2015-03-31 16:10 -0700
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Chris Angelico <rosuav@gmail.com> - 2015-04-01 10:36 +1100
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ian Kelly <ian.g.kelly@gmail.com> - 2015-03-31 17:43 -0600
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-04-02 23:31 +0200
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? sohcahtoa82@gmail.com - 2015-04-02 15:26 -0700
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ian Kelly <ian.g.kelly@gmail.com> - 2015-04-02 18:21 -0600
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2015-04-03 16:40 +1100
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Chris Angelico <rosuav@gmail.com> - 2015-04-03 16:57 +1100
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Marko Rauhamaa <marko@pacujo.net> - 2015-04-03 10:13 +0300
                r"\"" ??? (was A simple single line, triple-quoted comment) Rustom Mody <rustompmody@gmail.com> - 2015-04-03 05:52 -0700
                Re: r"\"" ??? (was A simple single line, triple-quoted comment) Chris Angelico <rosuav@gmail.com> - 2015-04-04 01:40 +1100
                Re: r"\"" ??? (was A simple single line, triple-quoted comment) Rustom Mody <rustompmody@gmail.com> - 2015-04-03 08:14 -0700
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ian Kelly <ian.g.kelly@gmail.com> - 2015-04-03 09:25 -0600
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ian Kelly <ian.g.kelly@gmail.com> - 2015-04-03 00:40 -0600
                Re: A simple single line, triple-quoted comment is giving syntax   error. Why? Gregory Ewing <greg.ewing@canterbury.ac.nz> - 2015-03-27 11:43 +1300
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-28 19:06 +0100
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ian Kelly <ian.g.kelly@gmail.com> - 2015-03-26 12:32 -0600
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-26 19:56 +0100
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2015-03-27 10:15 +1100
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Tim Chase <python.list@tim.thechases.com> - 2015-03-26 18:47 -0500
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Ian Kelly <ian.g.kelly@gmail.com> - 2015-03-26 19:38 -0600
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Marko Rauhamaa <marko@pacujo.net> - 2015-03-27 07:34 +0200
              Re: A simple single line, triple-quoted comment is giving syntax error. Why? Dave Angel <davea@davea.name> - 2015-03-26 01:23 -0400
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-26 18:25 +0100
                Re: A simple single line, triple-quoted comment is giving syntax error. Why? Thomas 'PointedEars' Lahn <PointedEars@web.de> - 2015-03-26 18:30 +0100
          Re: A simple single line, triple-quoted comment is giving syntax error. Why? Marko Rauhamaa <marko@pacujo.net> - 2015-03-22 12:00 +0200

csiph-web