WordPress / WordPress/WordPress-Coding-Standards

Handbook: require one blank line before and after a namespace declaration

Open
#2,305 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Component: Core Focus: Modern PHP Type: Enhancement
Dominant language
PHP
Stars
2.8k
Forks
521
Avg merge
5d 20h
Merged PRs (30d)
1

Description

Is your feature request related to a problem?

A sniff should be added to address the following handbook rule:

Namespace declarations should have exactly one blank line before the declaration and at least one blank line after.

Ref: https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#namespace-declarations

Additional context (optional)

From an analysis done of available sniffs:

The "Namespace declarations should have exactly one blank line before the declaration and at least one blank line after" will probably also need a new sniff.
My research shows the following:

  • The PSR2.Namespaces.NamespaceDeclaration sniff, which is included in Extra can sort of cover the "after" part, as in: it check for exactly one blank line after, which is close to, but not exactly what we want.
  • The PSR12.Files.FileHeader sniff can check both "before" and "after", but will also, again, check for exactly one blank line.
    The problem with that sniff is that it currently is "all or nothing", it does not have modular error codes, so we cannot ignore some other things from that sniff (requires blank line between PHP open tag and file docblock), which makes it problematic to include the sniff.
    If upstream PR squizlabs/PHP_CodeSniffer#2729 would (finally) be merged, we could reconsider adding that sniff though.

Ref: https://github.com/WordPress/WordPress-Coding-Standards/pull/2247

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the PSR2.Namespaces.NamespaceDeclaration and PSR12.Files.FileHeader sniffs mentioned in the issue, along with the linked WordPress Coding Standards pull request. Determine how the new sniff should enforce the namespace spacing rule without requiring unrelated checks. Done means the sniff and its coverage match the handbook requirement.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.