Our documentation standards (Documentation link) are currently silent about whether or not there should be a blank line between '<?php' and the the start of the @file docblock. The purpose of this issue is to clarify whether such a blank line should be a suggested 'best practice', or even required as a part of our documentation standard(s).

Currently, most Drupal @file docblocks include such a blank line before the start of the docblock. Should this become a standard in the name of consistency, and inclusion in automated coder review process(es)?

Comments

tim.plunkett’s picture

I did a quick check on which is more common:

75 files have no space between the php tag and the docblock
2416 files have a space between the php tag and the docblock

I think it's rather clear what we should do here.

Lars Toomre’s picture

That is pretty conclusive evidence @tim.plunkett. Should we modify [#1354] to make this a formal requirement?

If we do so, we can then add the appropriate check as a part of the automated coder review process.

jhodgdon’s picture

Issue tags:+coding standards

Why is this even worth worrying about? I understand wanting to have standards, but I don't think the readability of the code is changed for the better/worse with or without the blank line.

Having more standards that don't actually provide benefits just leads to developers being frustrated with having more things to remember. I propose that we not adopt a standard for this.

jhodgdon’s picture