Make WordPress Core

Opened 21 months ago

Last modified 21 months ago

#56582 new enhancement

Decide how to format multi-line comments in global scope.

Reported by: costdev's profile costdev Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: General Keywords: 2nd-opinion
Focuses: docs, coding-standards Cc:

Description

The PHP Documentation Standards include formats for various types of comment.

However, there is no clear description of what to use for multi-line comments in global scope.

For example:

3. Requires and Includes
Files required or included should be documented with a summary description DocBlock.
Optionally, this may apply to inline get_template_part() calls as needed for clarity.

However:

5. Inline Comments
Inline comments inside methods and functions should be formatted as follows:

5.2 Multi line Comments

   /*
    * This is a comment that is long enough to warrant being stretched over
    * the span of multiple lines. You'll notice this follows basically
    * the same format as the PHPDoc wrapping and comment block style.
    */

Important note: Multi-line comments must not begin with /** (double asterisk) as the parser might mistake it for a DocBlock. Use /* (single asterisk) instead.

Note: It's quite possible that the inline multi-line format just never expected to have to cover multi-line comments in global scope and was too specific in saying "inside methods and functions".

This leads to inconsistent formats and unnecessary discussion about what is correct.

Let's decide on a format that is appropriate.

Should we use /**, which is described for other items in global scope, or, as this format typically denotes something extra important (such as requires/includes, docblocks, class members, pre-existing filter docblocks), should we instead use the already existing multi-line comment format of /*?

Change History (4)

#1 @costdev
21 months ago

  • Keywords 2nd-opinion added

This ticket was mentioned in Slack in #core by costdev. View the logs.


21 months ago

#4 @dingo_d
21 months ago

I'm in favor of following the PSR-5 standard. They are using /** for any kind of structural element (check the documentation for the description of a structural element definition).

Multiline comments (starting with just one \*) should be used for non-essential explanations inside the code (like inside the function body) IMO.

Note: See TracTickets for help on using tickets.