PSR-12: closing brace MUST NOT be followed by any comment

[Bill Lee]

Section 4 states, "Any closing brace MUST NOT be followed by any comment or statement on the same line."  

I have a style that includes commenting on closing braces of long blocks to help readability. For example,

class MyClass
{
   ...
} // MyClass

The section 4 statement disallows this style. What is the reason for that?

[Andreas Möller]

I have a style that includes commenting on closing braces of long blocks to help readability. For example,

class MyClass
{
   ...
} // MyClass

How about not writing long blocks to help with readability?

There are a range of possibilities to refactor your code to avoid the need for comments altogether. See https://refactoring.com/catalog/. 

Best regards,

Andreas

[Joe T.]

Refactoring to smaller blocks isn't always practical, particularly with older legacy code. i've often used the style described, because inevitably, some hint that describes the block is more helpful than nothing at all. The project i currently work with is a nightmare of inconsistent patterns, procedural logic crammed into class methods, etc. Just getting things documented to understand inner workings of individual blocks (let alone whole functions) has been a long, slow process.

That said, perhaps moving the "end-of" comment to the line inside or after the terminating } can be helpful in most cases, but not perfect.

                }
                // END foreach($rows)
            }
            // END while ($count)
            // END ridiculously large if ($foo)
        } elseif ($bar) {
            // ...
        }
        // END ridiculously large if/elseif chain
        // END of foo()
    }
}

There's no ideal solution, given other rules about splitting chained controls like "} else[if ()] {" because there's no good placement of such a comment, nor good way to format it if complying with all the rules.

[Alexander Makarov]

Any good IDE and even simple code editors could highlight matching { and } so I see no practical use in having a comment.

[Joe T.]

By that thinking there's no need for code style standards at all because the IDE can do all the heavy lifting. Highlighting matching braces is fine, if they're both on screen. More advanced IDEs go as far as showing you the opening line when it's out of current view. But in my opinion, that's a convenience and shouldn't replace the helpful text that immediately tells a programmer where they are. Ever tried to view code directly on a server using vi/vim/etc.? It's not quite as easy even with the limited IDE-like functionality.

If code is already good quality, i totally agree there should be no need for supplemental comments like those described. But it's not always that simple.

That said, i think i ultimately agree with Alexander. It doesn't warrant its own rule or an exception to any rules in the PSR. There are compromises that can be made, and as suggested, it's a much better decision to do the cleanup work that would eliminate the need for the extra comments. My team's style guide uses PSR 1/2/12 as a base, and makes certain accommodations for legacy code and coaxing developers toward better practices. These end-of comments help us for our purposes, but when we rewrite this application on a new framework, the expectations for better code will go way up.

-jlt

[Bill Lee]

With my original query, I was never suggesting that the closing comments be a part of the PSR, I was merely questioning the “MUST NOT” mandate which seemed overly restrictive. It complicates using the PSR as a foundation for standards that could be derived from it (should they prefer the style I suggested, for example).

[Alice Wonder]

I do not use an IDE. I do not like them.

Typically the only comments I put at the end of a bracket is for end of class and end of function. End of class is not needed when the file only contains a class, but it provides visual consistency.

I'm not sure why some people care if there is a comment at end of a closing bracket. Why does it matter to them?

[Alessandro Lai]

We discussed that as WG, and we concluded that having a comment in the same line of a closing bracket can hinder readability, due to the fact that the closing bracket could not be seen; also, not only IDE but basically any code editor (even vim) have bracket highlighting.

[Alice Wonder]

I guess that's fine. It's just a recommendation, I can choose to ignore that part of it in my own code.

Just a note though - I don't use an IDE, many people do not.

And while the matching opening { is highlighted, when I have to look up to see it it distracts my mind from what I'm doing.

So to solve what is a distraction for some creates a required distraction for others over something that either party could easily adjust to their own preference with phpcs when working on someone else's code.

[Daniel Hunsaker]

This last point feels like an agreement for not having a coding standards PSR at all... "Just preprocess all the code you ever work with so it follows whatever style you personally prefer" is pretty much where we started before PSR-2. Not something I disagree with, mind - that kind of flexibility is important in practice - but still something to keep in mind/think about, IMO.

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/d6dffd82-8657-4410-a6ae-79f13373b849%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Greg Sherwood]

While I disagree with this specific part of the standard, having it in there at least means a decision has been made and code will be more consistent for it. Coding standards should be opinionated, and I think PSR-12 needs more rules and not less.

Greg