Blank lines in PSR-2

[Patrick Mulvey]

PSR-2 repeatedly mentions "blank lines" that MUST or MAY be put in certain positions (e.g. a blank line is required after a namespace declaration). But it never defines what is meant by a blank line - is a blank line a line with only whitespace characters on it, or must it contain only a newline character?

If I'm working with indented code (say in a class definition or something), my blank lines will contain spaces up to the same indentation level as the surrounding code, although they will appear blank. Is this acceptable? Is there any preference one way or the other?

[Carlos Campderrós]

Hi,

On Thu, Sep 27, 2012 at 4:07 PM, Patrick Mulvey <pdmu...@gmail.com> wrote:

PSR-2 repeatedly mentions "blank lines" that MUST or MAY be put in certain positions (e.g. a blank line is required after a namespace declaration). But it never defines what is meant by a blank line - is a blank line a line with only whitespace characters on it, or must it contain only a newline character?

PSR-2 at section "2.3 Lines"  says:
     "There MUST NOT be trailing whitespace at the end of non-blank lines."

i.e. it does not make any point about trailing whitespace on blank lines. So I guess whatever you do should be fine according to the standard.

 

If I'm working with indented code (say in a class definition or something), my blank lines will contain spaces up to the same indentation level as the surrounding code, although they will appear blank. Is this acceptable? Is there any preference one way or the other?

--
Si no puedes deslumbrar con tu sabiduría,
desconcierta con tus gilipolleces

[Sebastian Krebs]

2012/9/27 Carlos Campderrós <gilipollas.d...@gmail.com>

Hi,

On Thu, Sep 27, 2012 at 4:07 PM, Patrick Mulvey <pdmu...@gmail.com> wrote:

PSR-2 repeatedly mentions "blank lines" that MUST or MAY be put in certain positions (e.g. a blank line is required after a namespace declaration). But it never defines what is meant by a blank line - is a blank line a line with only whitespace characters on it, or must it contain only a newline character?

PSR-2 at section "2.3 Lines"  says:
     "There MUST NOT be trailing whitespace at the end of non-blank lines."

i.e. it does not make any point about trailing whitespace on blank lines. So I guess whatever you do should be fine according to the standard.

Can anybody explain my, why there is this restriction to non-blank lines only?

 

 

If I'm working with indented code (say in a class definition or something), my blank lines will contain spaces up to the same indentation level as the surrounding code, although they will appear blank. Is this acceptable? Is there any preference one way or the other?

--
Si no puedes deslumbrar con tu sabiduría,
desconcierta con tus gilipolleces

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
github.com/KingCrunch

[justin]

On Thursday, September 27, 2012 at 7:18 AM, Sebastian Krebs wrote:

2012/9/27 Carlos Campderrós <gilipollas.d...@gmail.com>

PSR-2 at section "2.3 Lines"  says:
     "There MUST NOT be trailing whitespace at the end of non-blank lines."

i.e. it does not make any point about trailing whitespace on blank lines. So I guess whatever you do should be fine according to the standard.

Can anybody explain my, why there is this restriction to non-blank lines only?

 

Because some people like to keep blank lines indented to the level of the surrounding text.

PSR-1/2 do this sort of thing in several places. They explicitly leave room open for variation where there are different preferences and no clear advantage either way. 

-- j

[Carlos Campderrós]

On Thu, Sep 27, 2012 at 4:18 PM, Sebastian Krebs <kreb...@gmail.com> wrote:

2012/9/27 Carlos Campderrós <gilipollas.d...@gmail.com>

PSR-2 at section "2.3 Lines"  says:

     "There MUST NOT be trailing whitespace at the end of non-blank lines."

i.e. it does not make any point about trailing whitespace on blank lines. So I guess whatever you do should be fine according to the standard.

Can anybody explain my, why there is this restriction to non-blank lines only?

I really have no recall of that being that way for a reason, but I guess that's because how different editors/IDEs work. When you indent a group of lines in vim, the blank lines remain empty (i.e. only the \n character), but in netbeans they are indented too (i.e. adding tabs/spaces, depending on your configuration). If the standard were to force a behavior on this aspect it could be problematic for those people using an editor/IDE that does behave the other way.

[Patrick Mulvey]

PSR-1/2 do this sort of thing in several places. They explicitly leave room open for variation where there are different preferences and no clear advantage either way. 

I have to disagree with that. It isn't explicit at all. To me it is an undefined term, and it's hard to judge the intent of the author based on that. The term "blank line" has no formal definition - my idea of a blank line may conflict with yours, or the author's. Section 7 of PSR-2 lists some elements of style which are intentionally not mentioned by the document - blank lines are not one of them. So we end up with this vague term appearing repeatedly throughout the document, which may be interpreted in different ways by different people. This leads to the possibility of conflicting expectations and implementations - i.e. the very thing these standards are trying to avoid. 

To "explicitly" leave it open for variation, you have to actually say it's open for variation, not just omit any mention of it from the document. Explicitly leaving it open would be saying something like "A blank line is one with no visible characters on it. It may optionally include whitespace characters, e.g. for matching code indentation". As it is, it's undefined, which is a source of uncertainty. 

It's worth noting that what constitutes a blank line has already spawned some confusion and disagreement.

Because of this, I think it would be helpful to add a glossary of terms to the PSRs, to clarify potentially ambiguous language. 

[Sebastian Krebs]

2012/9/27 Patrick Mulvey <pdmu...@gmail.com>

PSR-1/2 do this sort of thing in several places. They explicitly leave room open for variation where there are different preferences and no clear advantage either way. 

I have to disagree with that. It isn't explicit at all. To me it is an undefined term, and it's hard to judge the intent of the author based on that.

That's it: PSR-2 is explicit about, that it doesn't make an explicit statement here. This means: It is just up to you.

 

The term "blank line" has no formal definition - my idea of a blank line may conflict with yours, or the author's. Section 7 of PSR-2 lists some elements of style which are intentionally not mentioned by the document - blank lines are not one of them. So we end up with this vague term appearing repeatedly throughout the document, which may be interpreted in different ways by different people. This leads to the possibility of conflicting expectations and implementations - i.e. the very thing these standards are trying to avoid. 

To "explicitly" leave it open for variation, you have to actually say it's open for variation, not just omit any mention of it from the document. Explicitly leaving it open would be saying something like "A blank line is one with no visible characters on it. It may optionally include whitespace characters, e.g. for matching code indentation". As it is, it's undefined, which is a source of uncertainty. 

It's more "a source of freedom for own decisions" :)

Don't know, what's so complicated. It says "empty line", which means at least "no printable character", but even nothin more. It's _really_ up to wether your want the newline character intended with whitespaces, or not.

 

It's worth noting that what constitutes a blank line has already spawned some confusion and disagreement.

Because of this, I think it would be helpful to add a glossary of terms to the PSRs, to clarify potentially ambiguous language. 

 

On Thursday, September 27, 2012 3:45:43 PM UTC+1, Justin Hileman wrote:

On Thursday, September 27, 2012 at 7:18 AM, Sebastian Krebs wrote:

2012/9/27 Carlos Campderrós <gilipollas.d...@gmail.com>

PSR-2 at section "2.3 Lines"  says:
     "There MUST NOT be trailing whitespace at the end of non-blank lines."

i.e. it does not make any point about trailing whitespace on blank lines. So I guess whatever you do should be fine according to the standard.

Can anybody explain my, why there is this restriction to non-blank lines only?

 

Because some people like to keep blank lines indented to the level of the surrounding text.

PSR-1/2 do this sort of thing in several places. They explicitly leave room open for variation where there are different preferences and no clear advantage either way. 

-- j

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/sJeN84kEg4YJ.

For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
github.com/KingCrunch

[Patrick Mulvey]

Okay, fair enough. Maybe I was over-thinking it, and I'll take your point that if the specification is silent on an issue it implicitly grants permission to do whatever you want. 

I would however argue that if the spec is going to mandate that I use a blank line somewhere, it should define what is meant by a blank line to remove any possibility for confusion. PSR-2 uses the phrase "blank line" 8 times, 6 of them in conjunction with a MUST or MUST NOT clause. If the spec is telling me I MUST add something to my code, it only seems reasonable that it should provide a clear explanation of what it wants.

Also, as seen here and here there have been previous instances of people being confused by ambiguous terminology, leading to lengthy discussions over the correct interpretation of those terms. So I still think a glossary of terms to define what is meant by things like "blank line" or "use block", which probably mean something specific to the author but are not necessarily obvious to everyone else, is a good idea. 

[Hari K T]

Hi Guys, 

Recently there was a discussion about the same in PHP_CodeSniffer . Probably you will get the right answer . Also if you feel there is something lagging , do fork and give a PR and call for votes.

https://github.com/squizlabs/PHP_CodeSniffer/pull/57

https://github.com/squizlabs/PHP_CodeSniffer/pull/42#issuecomment-8838823

the correct interpretation of "a single blank line" is "a single newline". For example, if the last character of the file is a closing brace (as it is with a class file), the ending characters should be "}\n". Hope this helps.

Thanks

Hari K T
M: +91-9388758821 | W: http://harikt.com/blog

To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/lIAL_y1WydYJ.

[Patrick Mulvey]

Right, and the definition given in that discussion (by the primary author, Paul Jones) is a single newline character. This conflicts with the other feedback given here, as it seems to suggest that whitespace characters are not acceptable on a blank line.

[Sebastian Krebs]

OK, now I'm confused too. That an author sais something (even if it's the "primary" author) doesn't mean, that it is accepted as long as it is not part of the standard. OK, I'm with Jones, that I would never put whitespaces on an empty line (besides that PhpStorm removes them on save anyway ;)), but I don't know how useful it is to _enforce_ this. One step further: If the standard wants to enforce (or even encourage) it, it should be mentioned somewhere (like Hari suggested).

2012/9/28 Patrick Mulvey <pdmu...@gmail.com>

To view this discussion on the web visit https://groups.google.com/d/msg/php-fig/-/jgKHOSaZe1AJ.

For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
github.com/KingCrunch

[Paul Jones]

On Sep 27, 2012, at 3:07 PM, Patrick Mulvey wrote:

> I would however argue that if the spec is going to mandate that I use a blank line somewhere, it should define what is meant by a blank line to remove any possibility for confusion.

This is a fair criticism. As the guy who shepherded PSR-1 and 2 through the process, allow me to propose this definition:

"A blank line is any line composed only of zero or more spaces followed by a newline."

(Spaces, not tabs, as PSR-2 specifies spaces for indentation.)

As noted previously in this thread, some developers prefer to have indented blank lines between indented non-blank lines, so that when scrolling down, the cursor doesn't jump left and right. Similarly, some editors, when indenting a block of lines, will indent otherwise blank lines as well. But some would have the lines with no spaces in them at all. PSR-2 makes no recommendation either way.

I would argue that the rule saying "All PHP files MUST end with a single blank line" is a special case of blankness, meaning "the last character is a single newline not preceded by any other whitespace."

Yes, it's inconsistent; happy to hear about terminology that would resolve it. Similarly, happy to hear other variations of the definition so we can come to an agreement on the proper terminology.

Hope this helps, please let me know if it does not.

/me goes back to drinking his manhattan


-- pmj

[Sebastian Krebs]

2012/9/28 Paul Jones <pmjo...@gmail.com>

Whats about just "All PHP files MUST end with (exactly?) two newline characters"? This removes the term "blank line" from the definition, what allows to define "blank line" at will without affecting the EOF-special-case.

 

Hope this helps, please let me know if it does not.

/me goes back to drinking his manhattan


-- pmj

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
github.com/KingCrunch

[justin]

On Tue, Oct 2, 2012 at 11:35 AM, Sebastian Krebs <kreb...@gmail.com> wrote:
> Whats about just "All PHP files MUST end with (exactly?) two newline
> characters"? This removes the term "blank line" from the definition, what
> allows to define "blank line" at will without affecting the
> EOF-special-case.

In this case, I think it's actually "All PHP files MUST end with a
newline character". IIRC, there was a discussion about this a while
back, and the conclusion was reached that a "blank line" is shown in
most editors if there's a trailing newline, and that's what the
standard was referring to in this particular case. Just one, not two
newlines :)

--j

[Paul Jones]

Correct, and I caused confusion by saying "two newlines" when I should have said one. (That misstatement was revealed and revisited in a separate conversation regarding code sniffers, where I had to correct myself. :-/)


-- pmj

[Sebastian Krebs]

2012/10/2 justin <jus...@justinhileman.info>

Thought twice about it and took the wrong one: Yeah, that's what I meant ... ;) But isn't this all: "Files MUST end with a newline"?

--j

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To post to this group, send email to php...@googlegroups.com.
To unsubscribe from this group, send email to php-fig+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
github.com/KingCrunch

[Jason Judge]

This question keeps coming up, and will keep coming up so long as there is no lower-level foundation on these standards to define such things. This thread, and earlier threads, demonstrates nicely how difficult it can get if we need to keep redefining such things as too high a level.

For example, the PSRs that concern code structure and formatting, should not be trying to define what a file is. That needs to be defined elsewhere at a foundation level. Code just sits in files of code. Those files are formatted as files of code. There should be no further need to define the structure of a file when talking about code - talk of newlines and whether they appear on the end of a line or file, is just not relevant.

What is the format of a source code file? Well, a file is made up of one or more lines. What is a line? It is zero or more non-newline characters followed by a newline. What is a blank line? It is a line with no characters before its terminating newline. Or perhaps it can contain zero or more spaces only? Maybe there is a distinction between an empty line containing nothing, and a blank line containing only white space? Whatever the definition, it should not be something that needs to be dug up each time a new PSR is written, unless of course it needs refining.

The format of a file may also need to include character encoding/charactersets - what is allowed, what is not, and perhaps when, and how they should be identified. After that, the language-specific PSRs only need to talk about files, lines, empty lines and blank lines. They may need to mention trailing white space, but that is firmly in the code formatting realm, along with indentation.

How should a source file be terminated? From my definition above, it ends in a newline. I have not declared that - it just drops out of the definition of what a file is and a line is. It does not need to be explicitly mentioned again. If a PSR then states that a file must end "in a blank line", then that also drops out of the definition - it has two newlines (that may or may not be separated by one or more spaces, depending on the definition of "blank"). IMO that is not right - it is not was intended by that statement. And that is why we must stop trying to define low-level file formats in language-formatting PSRs, because it just pulls in inconsistencies when intent of meaning (well, I know what I meant) conflicts with other meanings of the same term at other levels.

I can see how we got to this point, because the standard jumped in at a level that would be of most use to PHP developers and projects. That, unfortunately, means that some of the basic foundations were not laid down first. Everyone here thinks they understand it fully, but I still see statements being made about file and line formats that simply conflict with other people's statements, and that is a distraction that is not going to help in the long term.

I hope that makes sense. There *must* be a standard somewhere already defined that can give us the terms and definitions we need to settle these things in an unambiguous and understandable way. Can we not find one and run with it? (I say "we" as a mere observer to the group, but I really think a trick is being missed here.)

-- Jason

-- Jason

[Jason Judge]

> But isn't this all: "Files MUST end with a newline"?

I would argue not. The unix convention text file, which it looks like the PSRs are following, state that all *lines* must end in a newline. The fact that a file must end in a "line", because a file consists of "lines", means that the file ends in a newline merely as a consequence of that.

-- Jason

[Patrick Mulvey]

On Friday, September 28, 2012 4:42:03 AM UTC+1, pmjones wrote:

    "A blank line is any line composed only of zero or more spaces followed by a newline."

That definition works

 

(Spaces, not tabs, as PSR-2 specifies spaces for indentation.)

As noted previously in this thread, some developers prefer to have indented blank lines between indented non-blank lines, so that when scrolling down, the cursor doesn't jump left and right.  Similarly, some editors, when indenting a block of lines, will indent otherwise blank lines as well.  But some would have the lines with no spaces in them at all. PSR-2 makes no recommendation either way.

I would argue that the rule saying "All PHP files MUST end with a single blank line" is a special case of blankness, meaning "the last character is a single newline not preceded by any other whitespace." 

Yes, it's inconsistent; happy to hear about terminology that would resolve it.  Similarly, happy to hear other variations of the definition so we can come to an agreement on the proper terminology.

Because it's a special case, I think it should avoid the term "blank line" to avoid polluting the definition. Why not just modify this rule to read "MUST end with a [single?] newline character"? That way the term "blank line" remains consistent.