Re: One more thing ...

On Sat, Apr 5, 2008 at 10:10 PM, Greg Sherwood <gsherwood@squiz.net> wrote: > Chuck Burgess wrote: > > > On Sat, Apr 5, 2008 at 7:35 AM, Helgi Þormar Þorbjörnsson < > > helgith@gmail.com> > > wrote: > > > > > > > > > Okey that's what I was talking about, 148 should not be an error, not > > > even close > > > > > > And I'm not sure what the heck 195 is about ... Who cares if there is > > > a > > > line break or not ? (I rather like having a line break actually) and > > > for the > > > last error I'm a bit stumped > > > > > > Lets hope Greg can fix those or at least turn them into warnings > > > ......... > > > > > > - Helgi > > > > > > On Sat, Apr 5, 2008 at 5:25 AM, Joe Stump <joe@joestump.net> wrote: > > > > > > > > > > > > > FILE: /Users/jstump/dev/foo.php > > > > > > > > > > > > > > > > > > > > > > -------------------------------------------------------------------------------- > > > > > > > > > > FOUND 3 ERROR(S) AND 1 WARNING(S) AFFECTING 3 LINE(S) > > > > > > > > > > > > > > > > > > > > > > -------------------------------------------------------------------------------- > > > > > > > > > > 72 | WARNING | Line exceeds 85 characters; contains 105 characters > > > > 148 | ERROR | There must be exactly one blank line before the > > > > tags in > > > > | | function comment > > > > 195 | ERROR | Parameters must appear immediately after the > > > > comment > > > > 195 | ERROR | Expected 1 space after the longest variable name > > > > > > > > > > > > > > > > > > > > > > -------------------------------------------------------------------------------- > > > > > > > > > > That was against this file: > > > > > > > > http://pear.php.net/manual/en/standards.sample.php > > > > > > > > --Joe > > > > > > > > > > > > > > > I believe the purposes of whoever wrote the examples in the manual > > (which is > > what Greg uses as his "gold standard" of what the PEAR CS rules are), > > you > > highlight your params tags more than any others by listing them before > > all > > others, and you segregate them from the others by a leading empty line > > and a > > trailing empty line. > > So, that I believe is why the documented example of a proper PEAR CS'd > > docblock looks that way... and I'm sure Greg's reasoning for enforcing > > it is > > solely because the example looks that way. > > > > > Exactly right. I try to not make any assumptions about why the coding > standards say what they do because they were written before I got here. I > just try to enforce them as per the standard. In this case, the sample file > clearly states "Please take note of the vertical and horizontal spacing. > They are part of the standard." If you read the entire standard, you will > interpret that as meaning that deviations from the sample file spacing are > errors. I remember emailing PEAR-DEV or PEAR-QA quite a while ago about the > sample file containing errors itself and IIRC I was asked to ignore those > and favor the textual description where a conflict occurs. > > When I wrote the PEAR standard, I made a decision to code in all the > errors, no matter how annoying, and select the error or warning level > depending on how the standard was worded. This has at least allowed PEAR > developers to see how poorly parts of the standard are written, enforced and > followed. There may be a very good reason for this (e.g., too time > consuming) but until you've seen all the errors you can't possibly know > which ones you'd like to remove from the standard. > > Considering I'll need to do a fair bit of work to get the new standards > into phpcs when the current RFC passes, now is a good time for all PEAR devs > to decide what we do and do not want in our current standard. Removing > standards, or changing them from errors to warnings, is dead easy for me, so > go nuts with the suggestions. However, I do think the written standard needs > to be updated at the same time as phpcs to ensure consistency, which is why > I don't make changes based on single emails. I wait until the written > standard is changed as that indicates to me that someone from QA (I assume) > has taken the responsibility for that decision. /me raises his hand I'm one of those QA guys :-) But well standards changes should be changed with approval from the community IMHO, hopefully Christian can add in a clause that we won't be anal about couple of spaces in the docblock and same goes for the aligning of = (I think that's already in his RFC if I'm not mistaken ?) - Helgi