Psr 1 style guide #25

Merged
merged 36 commits into from Jun 4, 2012

Conversation

Projects
None yet
Contributor

pmjones commented Mar 25, 2012

Final draft of the style guide, with the survey data incorporated.

gnugat commented Mar 26, 2012

I don't really get why class constants, properties, and methods have a different brace placement than control structures?
Is it because most coding style mix them? If that's the case I would understand, but else I find it a bit unconsistent...

Contributor

pmjones commented Mar 26, 2012

@gnugat It is because most projects in the survey follow the K&R style, which has control braces on the same line but class and method braces on the next line. Note the survey data at the end of this commit:

https://github.com/pmjones/fig-standards/commit/f418d79179c79a170210614f14e3d7c78569d3eb

milesj commented Mar 26, 2012

PSR should not define a standard for syntax placement. The only thing the PSR should do is define standards for interoperability and packaging schemas.

@milesj isnt that what PSR-0 did ?

milesj commented Mar 26, 2012

Yes, what I am saying is that many things in PSR-1 regarding syntax should not be enforced or even mentioned. Telling someone where to place their curlies, or how to format if statements, whether to use tabs or spaces, how to place modifiers, etc, have nothing to do with programming or interoperability. All it has to do with is personal preference, which differs greatly between each individual.

And on top of that, it's not like I will be editing your code, or you editing mine, so why do we care about those things? The only thing we need to care about is situations where both our code is used in the same environment.

Out of this whole PSR, the only thing that I believe are necessary are:

  • Use only <?php and <?= opening tags for PHP code; leave out the closing ?> tag when the file contains only PHP code.
  • Namespace all classes
  • Declare class names in StudlyCaps (PSR-0)
  • Declare method names in camelCase (up for debate)
  • Use only UTF-8 (no BOM) for PHP code. Do not use other character encodings.
  • Use the Unix LF (linefeed) line ending on all PHP files.

IDEs render most of these suggestions obsolete anyways.

Contributor

pmjones commented Mar 26, 2012

Your opinion is duly noted; however, please note the introductory text:

"This guide is derived from commonalities among the various member
projects. If one project has its own style guide, that's fine for that
project. But when various authors collaborate across multiple projects, it
helps to have one set of guidelines to be used among all those projects.
Thus, the benefit of this guide is not in the rules themselves, but in the
sharing of those rules."

milesj commented Mar 26, 2012

Yes but like I said, we won't be working in each others code (for the most part), so defining syntax rules aren't needed.

@milesj well in a perfect world we all collaborate on stuff and help each other out if a bug is found :) But that is the perfect world, but i dont see why we cant have rules helping with that by reducing the barrier a bit.

milesj commented Mar 26, 2012

Aesthetic syntax is just that, aesthetics. Nothing in your comment supports the need for these rules. Using tabs over spaces or placing curlies on different lines isn't reducing any barrier.

In my opinion, PSR should only convey rules for hard requirements.

Contributor

harikt commented Mar 26, 2012

@milesj I am not sure whether you missed why a standard is being introduced.
Each project for eg : Symfony2 , Drupal , PHPBB, ZF2 , Aura, Doctrine2 and many more are making use of components or libraries of different other projects.
So lets take Drupal , Drupal going to use many of Symfony2 components . Both have a different set of CS. And in the collaboration its always a good way to have a single CS. As mentioned by @pmjones these standards are taken comparing various projects which were added in the Excel at one time.
Hope that make sense.

Contributor

pmjones commented Mar 26, 2012

@milesj "Using tabs over spaces or placing curlies on different lines isn't reducing any barrier." Many of us believe it is reducing a barrier, and are working toward that. I get that you don't agree; but then, if they don't really matter, then it doesn't matter what we all agree on, so long as we agree on it.

milesj commented Mar 27, 2012

Completely disagree.

How someone structures there syntax should not matter, just as long as the libraries work together in the same environment without causing conflicts. Thats all this standard should be used for, a set of guidelines for interoperability and possibly a set of interfaces to follow. I'll end this discussion here and it should be in the Groups more than anything.

cbandy commented Mar 27, 2012

I think the Properties section should be reduced to the few requirements that are actually stated:

Declare visibility on all properties; do not use var to declare a property, and declare only one property per statement.

In the same vein, this sentence should be removed from the Methods section:

Some projects prefix method names with a single underscore to indicate protected or private visibility; this guide discourages but does not disallow that practice.

This paragraph should be removed from the Control Structures section:

N.b.: There appears to be no consistency between projects, and often not even within the same project, on the use of else if vs elseif. This guide encourages the use of elseif so that all control structures look like single words.

In my opinion, the Control Structures section is too vague. It begins with a series of general rules, then omits specific rules for specific structures. For example, is the position of else a suggestion or a requirement? Is the presence of a // no break line a suggestion or a requirement?

Contributor

pmjones commented Mar 27, 2012

@cbandy We felt it was important to explicitly say "we make no recommendation on properties" so that it was clear nothing else should be used to imply a recommendation.

Re: methods, there are a lot of folks still using that, and while it's discouraged, we feel it's not exactly a problem.

Re: elseif, I wanted to point out that we did look at the projects, and that they themselves don't have a standard ... then go on to suggest one.

The position of else is a requirement, as noted by the phrase " else and elseif are on the same line as the closing brace from the earlier body." Same goes for // no break, it's mentioned specifically in the lead-in to the example.

tcz commented Apr 17, 2012

Do we really need this? I mean most if IDEs can format your code in the way it's more comfortable for you to read if you really need this (see for example Netbeans Format command).

Not to mention that code formatting is something totally subjective, there are no arguments here. Who defines the standard and on what ground?

Oh, and don't forget: http://xkcd.com/927/

Has there been any discussion of standardizing whether to include an end of file new line?

Contributor

pmjones commented Apr 19, 2012

Strangely, no. Where have you been for the past two months? ;-)

pmjones and others added some commits May 4, 2012

sstok commented May 25, 2012

In the case of else/elseif how about not placing anything after the }.

if ($expr1) {
    // if body
} elseif ($expr2) {
    // elseif body
} else {
    // else body;
}

Becomes.

if ($expr1) {
    // if body
}
elseif ($expr2) {
    // elseif body
}
else {
    // else body;
}

This keeps it readable, does not ad extensive whitespace and gives a more natural flow as the statement is on its own line.
Only applying this to elseif could be done to, but that looks weird.

Contributor

mermshaus commented Jun 1, 2012

Is there a reason why sections 4.4 and 6 of PSR-2 use two or three spaces for indentation? That seems inconsistent to me.

Besides, there are two sections labeled 4.4 right now.

Contributor

RobLoach commented Jun 4, 2012

How is this different from #14 ? Should the two be merged?

Contributor

harikt commented Jun 4, 2012

@RobLoach the one you mentioned is a start and later through the various discussion , this PR is here.

Contributor

RobLoach commented Jun 4, 2012

@harikt Thanks for the clarification :-) .

pmjones added a commit that referenced this pull request Jun 4, 2012

Merge pull request #25 from pmjones/psr-1-style-guide
PSR-1 and PSR-2 passed; merge them into the main repo.

@pmjones pmjones merged commit 38dc2dc into php-fig:master Jun 4, 2012

Have ever read this:
http://en.wikipedia.org/wiki/Indent_style

Espesially the following part:

In old versions of the C programming language, the functions, however, were braced distinctly. The opening function brace of a function was placed on >the line following after the declaration section and at the same indentation level as the declaration (header of the function). This is because in the original C >language, argument types needed to be declared on the subsequent line (i. e., just after the header of the function), whereas when no arguments were >necessary, the opening brace would not appear in the same line with the function declaration. The opening brace for function declarations was an >exception to the currently basic rule stating that the statements and blocks of a function are all enclosed in the function braces.

sun pushed a commit to sun/fig-standards that referenced this pull request May 18, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment