1

Early on in my career I was advised to add additional spacing between source code and an inline comment, like so:

de_cologne = (i == 4711  # 1
              and j == 1799)  # 2

Note the two spaces.

Supposedly, the reason for doing this is to distinguish operators that we use to delimit comments from other operators. Presumably, this might help some poor reader that just now switched from reading a programming language in which the operator might mean something else (in particular with regards to arithmetic).

In my experience, even in Python where the practice is inscribed in PEP-8, the practice is rarely adhered to. I can well imagine this being less useful in some domains compared to others.

Is there a particular language in which this is good practice?

  • 1
    "...these questions aren’t educational in any way, because there’s no way to learn about the process of discovery. A particular community member, by virtue of their experience in the field, just happens to be able to take the limited information you remembered and fill in enough of the blanks to guess the correct answer... guessing game questions do not meet our goal of making the Internet better." (blog.stackoverflow.com/2012/02/lets-play-the-guessing-game) – gnat Sep 13 '17 at 16:33
  • 4
    Is that Python? The two-space-before-comment convention is codified in PEP-8, probably in order to emphasize the visual distinction between code and comments – amon Sep 13 '17 at 16:34
  • 9
    You're worrying a bit too much about this. The additional space is there as a visual thing to clearly distinguish the comment from the code. That's all. – Robert Harvey Sep 13 '17 at 17:06
  • 4
    Actually the real question is probably whether the benefit exceeds the cost, and since the cost is so small... – Robert Harvey Sep 13 '17 at 17:53
  • 1
    No doubt in 2017 that is pointless. A vast majority of developers use syntax highlighting, and those few that don't do not because they are so good they do not need additional help reading source code. – mattnz Sep 14 '17 at 3:24
1

Style is mostly a matter of opinion. Your best choice is to use the official style guide for your preferred language. Thanks to the comments, it appears that PEP-8 is one of such guides which enforce this rule.

Note that PEP-8 doesn't force you to put exactly two spaces, but at least two spaces. This means that you could have written:

de_cologne = (i == 4711      # 0x1267
              and j == 1799)  # 0x707

Although in this code, I would simply make the comments useless:

de_cologne = i == 0x1267 and j == 0x707

I suppose that the person who told you to do it was motivated by the visual aspect, although there could be much better ways to clearly separate the comments, for instance by putting them on a separate line in the first place.

Anyway, any decent text editor has syntax highlighting, which makes the comments distinct enough from the code to require any additional formatting effort.

Presumably, this might help some poor reader that just switched from a programming language in which the operator might mean something else

If a person switched from another programming language, it belongs to this person to learn the syntax of the new language. It's not your task to adapt your code to the persons who don't know the syntax, and you won't be able to do it anyway.

  • You see my point, then. I figured there might be a language in particular that prompted the response. As for syntax differences between languages - many of us switch between multiple languages a day; brain farts are human. I have mixed up the C XOR operator more times than I can count. – Caterpillar Sep 13 '17 at 17:40
1

Supposedly, the reason for doing this is to distinguish operators that we use to delimit comments from other operators.

If you are remembering correctly, this is a very valid reason.

At the end of the day, the purpose of any coding style is to make wrong code look wrong, which this does as you point out. Whether or not its part of PEP8 I don't think really matters, as the right coding style for a project is whatever fits the team's needs the best.

While some editors and langauge familiarity can make inline comments very obvious while working on the codebase, this relies on the assumption that your team will work on this codebase and in this language in perpituity. You'll likely eventually start only performing minimal maintenance on this codebase, and switch to a new langauge. When this occurs, it may be quite a bit easier to read this code with this style convention.

Presumably, this might help some poor reader that just switched from a programming language in which the operator might mean something else (in particular with regards to arithmetic).

Almost all professional programmers at some point in their career will find themselves having to read/modify code written in a language they are unfamiliar with (either because its new to them, or because they haven't used it for so long).

  • Thanks for the link! I'd add to the last paragraph that even when we work exclusively with languages that we're familiar with we sometimes find ourselves switching between multiple languages a day. – Caterpillar Sep 14 '17 at 17:37

Not the answer you're looking for? Browse other questions tagged or ask your own question.