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

tim.plunkett
he/him
Primary language English
Location Philadelphia
commented

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

lars toomre commented

That is pretty conclusive evidence @tim.plunkett. Should we modify #1354: [Obsolete] API documentation and comment standards 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

jhodgdon
she/her
Primary language English
commented
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

jhodgdon
she/her
Primary language English
commented
Issue summary: View changes
Status: Active » Closed (duplicate)
Related issues: +#2248463: Require a blank line after <?php

This is a duplicate of #2248463: Require a blank line after <?php