Ammendments to PSR-2

[Andrew Eddie]

Hi. I'd like to propose the following ammendments to PSR-2. See here for the first part:

https://github.com/eddieajau/fig-standards/commit/e01d0282c6c2764cd1c72596a60b3bc1d4ceaa8b

The changes here are:

1. A soft length limit, or a hard limit, or both MAY be required.

There is absolutely no reason why a code owner should not be able to enforce soft or hard limits.

2. A soft limit SHOULD be between 80 and 120 characters.

This fixes the completely illogical wording of the current text that implies the hard limit is 80 chars and the soft limit is 120 (that's backwards). 

3. Simplify note about spaces vs tabs.

I've removed the note about spaces being better because it helps with diffs and patches. It's simply not true because if you are consistent it works fine, but the note adds no value to the specification. The micro-alignment is actually the important bit for those that want to bother.

Ok, that's that.

I also want to propose we add some very generic requirements Docblocks. I've been looking around at many code projects that are claiming to be PSR-2 compliant (and they are), but frankly there in-code documentation, in some cases, sucks! It's really not good enough. 

Therefore, would it be out of order to add some minimum standards about Docblocks if there is to be an ammendment. The reason I ask is I assume that any ammendment will retire PSR-2 and change it to PSR-# (where # is the next available number)? So if there are changes, it's worth while doing something meaningful.

To that end I'd propose something like the following (in shorthand):

* Docblocks MUST be provided in the file header, for classes and their methods and their properites/constants, and for functions.

* File Docblocks MUST include @license and @copyright.

* Class Docblocks MUST include a short description/title and SHOULD include @since

* Class property/constant Docblocks MUST include @var with variable type and description

   and SHOULD include @since

* Class methods and functions MUST include a short description/title,

   MUST include @param where function arguments are provided,

   MUST include @return

   MUST include @throws if an exception is thrown in the method or function

   SHOULD include @since

Might be a few things I've missed but that's the minimum we should require (I'm not pariticularly worried about formatting and alignment at this time - present is better than pretty). And that would go for any scope - public, protected or private. Anything less is just being sloppy in my opinion (and I'd add it applies to all PHP code files, including tests). I'm not sure the @package and @subpackge is absolutely necessary anymore given we are in a post-namespacing world - I'll defer to the advice of the documentation tool writers there.

If there's any interest in moving forward on this, I'll forge ahead with some actual text. If not, then let's bury this quickly.

Thanks in advance.

Regards,

Andrew Eddie

[Patrick Mulvey]

1. I'm inclined to agree that a project owner should be able to enforce limits, as long as they are stricter than those given in PSR-2. The PSR-2 soft limit is 120, but if a given project wanted to use a soft limit of 100 I can't see how it could cause problems for anyone. If a project went the other way (e.g. set the soft limit at 150) then that could be problematic, but as long as the rules specify lines of <120 characters, a project should be able to do what they want. And of course, there's nothing stopping them from doing so now - they might not be compliant with that one clause of PSR-2, but I can't see that being a problem. They wouldn't even get any warnings from CS tools for doing so.

2. Have to disagree here - your version is more ambiguous than the spec is. The spec essentially says "try to keep lines <80 chars, if you go over 120 it will cause a warning, but line length will never cause an error". No problems there. Your amendment says "The soft limit on line length SHOULD be betwen 80 and 120 characters", which doesn't make sense. A limit should be a simple number, e.g. 120. You've given a range - "between 80 and 120". That's confusing - have you broken the soft limit at 80? Or at 120?

3. You are correct that there will be no problems with diffs, history etc. if you are consistent. What this note is trying to do is justify why PSR-2 mentions tabs vs. spaces at all - it's explaining that everybody needs to use the same standard (4 spaces) or it will cause problems. I think the authors realised that this might be an unpopular part of the spec, and they are trying to explain the reasoning, which is valid. The issue is not personal consistency, but consistency between projects. If you read it from that angle, it makes sense.

Docblocks have nothing to do with code style, so I don't think PSR-2 (or an amendment to it) should mention them at all. Docblocks were quite extensively discussed on the main mailing list a while back, but you might have to dig down a bit to find those discussions. But generally, I think what you're proposing (requiring use of specific docblocks) is a new proposal, and maybe it should be discussed separately in the main mailing list. 

[Andrew Eddie]

I light of the recent, ehum, conversations, concerning PSR-2, I'll put some more thought into this.

Regards,

Andrew Eddie