python multiline comment indent

Question

I have a Django project, and in some places we have multiline comments indented as follows:

field = models.IntegerField(default=0, null=True)  # 0-initial_email_sent
                                                   # 1-second_email_sent
                                                   # 2-third_email_sent

This clearly violates PEP, but, in my opinion, helps with readability. Of course, I could put comments like this:

# 0-initial_email_sent
# 1-second_email_sent
# 2-third_email_sent
field = models.IntegerField(default=0, null=True)

, but I would much rather prefer the first one.

Is there any way to indent comments as such without violating PEP?

Don't know if this is "canonical", but the [Python Style guide (PEP 8)](https://www.python.org/dev/peps/pep-0008/#comments) distinguishes between block comments and in-line comments. There is no such thing as in-line block comments. — tobias_k, Jun 29 '16 at 11:48
If your `field` were named `number_of_emails_sent`, and you used the appropriate integer value, then you wouldn't need the comment. — Aya, Jun 29 '16 at 12:08

bruno desthuilliers · Accepted Answer · 2016-06-29T13:57:45.037

4

Magic numbers are evil, so the best documentation here is to use named (pseudo) constants:

INITIAL_EMAIL_SENT = 0
SECOND_EMAIL_SENT = 1
THIRD_EMAIL_SENT = 2
field = models.IntegerField(default=INITIAL_EMAIL_SENT, null=True)

As a general rule, the less you have to comment the better (clear code needs no or very very few comments).

For a more general answer about where to place comments, specially multiline ones:

having the comments before the commented item is what most python users expect so for the majority of is it is "more readable"
it also makes code editing easier (you don't have comments mixed with code, you don't have to maintain comments indentation etc).

If it's your own personal project and you don't plan on sharing it or having anyone else working on it you are (hopefully) free to use any coding style / convention, pep08 is no religion, but if someone else ever have to work on your code he will certainly hate you for commenting this way.

edited Jun 29 '16 at 13:57

answered Jun 29 '16 at 12:02

bruno desthuilliers

75,974
6
88
118

1

He is talking about comment. Why introducing constants ? I am also a naive in python. Just asking question. I didn't understand your point here ? – Mahammad Adil Azeem Jun 29 '16 at 12:15
@AdilMalik: [What is a magic number, and why is it bad?](http://stackoverflow.com/questions/47882/what-is-a-magic-number-and-why-is-it-bad) – GingerPlusPlus Jun 29 '16 at 12:42
@GingerPlusPlus that's what i am asking Bruno to explain here. Still not sure why he thinks constants are better than triple-quote strings – Mahammad Adil Azeem Jun 29 '16 at 12:44
I fully agree that named constants are much better. However the question itself isn't about magic numbers, but about multiline comments. Probably my example is just bad, then. – Назар Топольський Jun 29 '16 at 13:06
@AdilMalik cf my added explanations. – bruno desthuilliers Jun 29 '16 at 13:58
1

@НазарТопольський I understand the question was not about magic numbers but my point was that clear code needs way less comments ;) – bruno desthuilliers Jun 29 '16 at 14:01
Now that you have actually touched the issue, I will accept this answer, because I do agree that such commenting style smells kinda bad. – Назар Топольський Jun 29 '16 at 14:58

score 0 · Answer 2 · edited May 23 '17 at 12:01

0

This question is duplicate of this question
You could also use multi-line comments like this.

"""
This is how yo can use Python Multi-line Comments
Line two is here.
Line three is here.
"""

edited May 23 '17 at 12:01

Community

1
1

answered Jun 29 '16 at 11:44

Mahammad Adil Azeem

9,112
13
57
84

[You just violated PEP 8](https://www.python.org/dev/peps/pep-0008/#string-quotes). – miradulo Jun 29 '16 at 11:48
@Mitch is it correct now ? Thanks i never knew that :) – Mahammad Adil Azeem Jun 29 '16 at 11:51
3

This is not a multi-line comment, it's a (triple-quoted) string. – bruno desthuilliers Jun 29 '16 at 12:00
2

Same question was asked here. and they said its a multiline comment. @brunodesthuilliers http://stackoverflow.com/questions/7696924/multiline-comments-in-python – Mahammad Adil Azeem Jun 29 '16 at 12:11
Multiline strings can be used as comments in that they can be used to describe something and they do not generate bytecode, however, they are not. For instance, if you place it just after function declaration, it will be treated as docstrings, they aren't highlighted as comments by IDEs I know about and, frankly, seem just odd. – Назар Топольський Jun 29 '16 at 13:11
2

@AdilMalik They are wrong. See: http://stackoverflow.com/a/38100436/172176 – Aya Jun 29 '16 at 13:11
@aya I would certainly upvote your comment if I could. Not only is the answer wrong, but also (in a way) dangerous, since it can lead to errors. – Назар Топольський Jun 29 '16 at 15:02

python multiline comment indent

2 Answers2