26

One of my answers was recently edited, fixing a typo (great) and also changing the style of the comments. IMO the new style is neither more readable nor does it add anything else, so I rolled back the edit and reapplied the typo fixes myself. Then I noticed that the edit comment included a reference to a "Jon Skeet Decree" as a reasoning for the change:

Made compliant with the Jon Skeet Decree - https://twitter.com/PeterMortensen/status/976400000942034944

The Twitter post links to an SO podcast where apparently Jon Skeet said he wants comments to have a leading space and start with a capital letter. Now, regardless of if you think that is a good idea or not (I personally think it's not applicable for comments that are not full sentences), I would assume the "Decree" mentioned on the podcast page is an attempt at humour and not a rule that must be followed. Thus it seems to fall under personal preference, and AFAIK edits should only apply fixes and should not be used to change code style to one's own preference. Thus, questions:

  1. Is my assumption correct that the "decree" is not an agreed-upon rule?
  2. Is it OK to edit one code style to another if this does not result in a significant increase in readability?
  3. If the answer to question 2 is yes, is it OK for me to roll back such an edit if I think the new style makes the post worse?

Here's an example of one comment before and after editing - before:

result = [0] * len(l1) * 2 #create result list of required size

After:

result = [0] * len(l1) * 2 # Create result list of required size
20
  • 2
    "Is it OK to edit one code style to another if this does not result in a significant increase in readability?" I would say not, but without seeing the edit difficult to say. You make the edit (to the code) sound like it's superfluous, which isn't a good reason to edit a question/answer.
    – Thom A
    May 3, 2021 at 15:18
  • @Larnu it was an edit to an answer, and the specific change was IMO superfluous even if you count the typo (but I would have been fine with just the typo fix). I added a before/after example to the post.
    – l4mpi
    May 3, 2021 at 15:21
  • 2
    Is it this edit? May 3, 2021 at 15:22
  • 1
    @JeanneDark yes. However I'm less interested in this single edit and more in the general case.
    – l4mpi
    May 3, 2021 at 15:24
  • 15
    IMHO the result is indeed more readable, but I would personally decree that an extra space before the comment token # and a period . at the end of the comment would be necessary. Please stand by as I go on an edit spree in your answers. I'm sure everything will end up just fine. May 3, 2021 at 15:38
  • 3
    @FrédéricHamidi go ahead, I'll edit your C code to Allman style in the meantime ;) On readability, I actually think the space after the # is (very slightly) harmful as now the # sticks out and feels like an operator.
    – l4mpi
    May 3, 2021 at 15:47
  • @Yatin this question is specifically not about a specific-edit so please don't add that tag. The specific edit was added as an example, but the main focus of the question is the general case (see the numbered questions in the middle).
    – l4mpi
    May 3, 2021 at 16:03
  • This tag is used to query the community on the specifics of a particular edit made or suggested on Stack Overflow or its Meta. -- seems applicable to me. (but I am ok if you don't want it) May 3, 2021 at 16:10
  • 3
    @Yatin the specific edit was the reason for asking the question but I tried to frame it in a more general way, as I'm more interested in how to react to similar edits going forward than the fate of the single edited post. IMO debating a specific edit is seldomly useful, and in this case would probably devolve into a discussion if the comment is more or less readable after the edit. I added the example only because people asked and the question was being downvoted initially (potentially due to lack of an example).
    – l4mpi
    May 3, 2021 at 16:19
  • 4
    You don't say what programming language the question is about, but fwiw the space in inline comments is a convention in some popular languages, see PEP-8 Inline Comments. I just checked and the post is in Python, so the edit is correct from a technical POV.
    – bad_coder
    May 3, 2021 at 16:29
  • 5
    @bad_coder Yeah 10Rep commented that it's part of PEP-8 below rene's answer. However PEP-8 is still just a style guide and far from universally approved, thus I would not call it "correct from a techical POV". It seems not more or less "correct" than postulating that C code on SO must only be written in one specific style.
    – l4mpi
    May 3, 2021 at 16:35
  • 1
    @l4mpi that's not true because it's prevalent practice and if that code gets pasted into any IDE or run through a linter it's going to emit warnings. If everyone were to ignore the style guides without reason (like occasionally saving vertical space) that'd be a problem multiplier with no upside to show for it. It seems to me the way you wrote this post purposely misrepresents the problem by not saying what the language in question is and not linking to the specific post.
    – bad_coder
    May 3, 2021 at 16:39
  • 2
    @bad_coder "prevalent practice" in your experience maybe, but in my current job I've not seen anybody use a PEP-8 conforming linter and I'm working here for 10 years now. We have a loose set of internally agreed practices for writing code, and most of that is the same or similar to PEP-8, but some parts such as the max line length are simply ignored because they're not useful. As I explained previously, I did not link to the specific post because it's not about the specific post but about the general case.
    – l4mpi
    May 3, 2021 at 16:42
  • 5
    @bad_coder you probably have not seen enough code then. But even if that were the case, that doesn't change the fact that it is a style guide and there are many of those - e.g. here's the google one, which is not PEP-8 compatible. Why should one style guide have priority over all others?
    – l4mpi
    May 3, 2021 at 16:53
  • 2
    OT: I strongly prefer the second style. To me it's much easier to read. May 3, 2021 at 17:10

1 Answer 1

64

I value the knowledge of Jon Skeet. I also value the relentless effort made by our Editor in Chief.

But no, Jon's commenting style is not mine and as long as I don't report to Jon I can stick to my own comment style in my code. The same goes for all other users that wrote answers.

Do not edit code is a general principle. Comments are part of the code. Don't touch it in an edit, unless you're 99,99% sure that an edit is needed, and not editing the code causes harm.

The only harm for a missing space and capital letter is a slight itch for Jon Skeet. We can live with that, so can he.

9
  • 13
    For what it's worth, that isn't Jon's decree, it's just a part of the style rules decreed by PEP 8. It's a programmers choice whether or not to follow those stylistic rules, and it shouldn't really be edited in a question. So, I guess you could call it Guido's decree ;)
    – 10 Rep
    May 3, 2021 at 16:13
  • 3
    @Programmer as I commented under the question, I think the extra space is slightly harmful to readability as detaching the # from the comment text makes it look like an operator. If it's more or less readable is probably dependent on what you're more familiar with, as well as how the comment is rendered by the IDE (color scheme / text style).
    – l4mpi
    May 3, 2021 at 16:39
  • @l4mpi hmm, that is a good point I would have never thought of alone !
    – TheEagle
    May 3, 2021 at 16:40
  • 28
    All comments in code should start with a 🤦‍♀️ ...
    – rene
    May 3, 2021 at 16:41
  • 3
    @l4mpi it won't look like an operator if you follow PEP8 which says to use 2 spaces before and one space after to properly separate the inline comment from the code. May 3, 2021 at 18:17
  • 2
    @10Rep So, I guess you could call it Guido's decree oh no no no, don't drag me into this discussion please :)
    – GuidoG
    May 3, 2021 at 19:21
  • Is it OK to edit commas in numbers that "should" have been decimal points? :)
    – Nick
    May 3, 2021 at 22:56
  • 1
    @GuidoG it would be funny if the real Guido replies to this ;) May 4, 2021 at 13:50
  • @Yatin wow, they actually have an account... lol.
    – 10 Rep
    May 5, 2021 at 0:45

Not the answer you're looking for? Browse other questions tagged .