Make WordPress Core

Opened 11 months ago

Closed 9 months ago

Last modified 9 months ago

#58459 closed enhancement (fixed)

Replace multiple single line comments with multi-line comments

Reported by: costdev's profile costdev Owned by: audrasjb's profile audrasjb
Milestone: 6.3 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs, coding-standards Cc:

Description

Overview

The PHP Inline Documentation Standards: Inline Comments section states:

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

Single line comments

// Allow plugins to filter an array.

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.
 */

A proposal to amend the Inline Documentation Standards for multi-line comments didn't get support.

There are quite a lot of cases when this standard has not been met in Core. As more files contain non-compliant comments, this leads to more instances to maintain consistency, with an aim to address all instances at once in the future.

The future is here!

Approach

For most cases, multiple single line comments can just be replaced with the multi-line comment format. Others may be "unnecessary" line breaks which can be changed to one single line comment.

Caveats

  1. The inline documentation standards state "inside methods and functions". Therefore, root-level use of multiple single line comments should not be changed. To change these would require a change to the standard, which is outside the scope of this ticket.
  2. When PHPCS is enabled, disabled, or sniffs are ignored, these should not use the multi-line comment format.
  3. As always, this excludes external libraries and files maintained in Gutenberg. Gutenberg-maintained files should be updated on the Gutenberg repository.

Related: #57839

Change History (38)

#7 @audrasjb
11 months ago

  • Owner set to audrasjb
  • Status changed from new to reviewing

#8 @audrasjb
11 months ago

Thanks @costdev! This looks good to me at a glance. I'll take more time for an in-depth review of each PR but BTW I'm wondering whether we should use this change to replace most verbs with third person singular…
https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#language

Last edited 11 months ago by audrasjb (previous) (diff)

#9 @costdev
11 months ago

@audrasjb Thanks! I split the PRs into groups of 20 files to try to make the review process a bit smoother 🙂

The Language section states:

A function, hook, class, or method is a third-person singular element, meaning that third-person singular verbs should be used to describe what each does.

So I think the third-person singular verbs are just for those docblocks rather than inline comments, right?

We could certainly correct things like missing ., capitalization and typos on the touched comments. That way, we don't need to wait until someone just happens to spot those issues.

#10 @costdev
11 months ago

FWIW, I'm happy to follow up with another ticket that specifically looks at docblocks and ensures they use third-person singular verbs. I've seen many of your commits to that effect and I'd definitely like to check out any remaining instances and get those fixed up.

#11 @audrasjb
11 months ago

Alright, let's not jump the gun and strictly focus on the goal of this ticket 👍

#12 @costdev
10 months ago

  • Keywords 2nd-opinion removed

#13 @costdev
10 months ago

@audrasjb What's your opinion on the best plan for when to commit this one?

My thinking:
Docs changes aren't a priority as we approach Beta 1, but I'm also thinking this is a sooner-the-better ticket to help avoid new instances being introduced as part of "consistent non-compliance" with the standard.

Depending on where the reviewing process is at, we may still be able to land the PRs soon (maybe even ahead of Beta 1?) and save time by not having to update the PRs with new instances introduced between now and commit.

#14 @audrasjb
10 months ago

Hey @costdev my plan is to commit this once beta 1 is released so most enhancement commits are done and we don't add conflicts to all the existing PRs, yeah 😅

#15 @costdev
10 months ago

Good point! 😂

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


10 months ago

#17 @audrasjb
9 months ago

In 56174:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Props costdev, audrasjb.
See #58459.

#18 @audrasjb
9 months ago

In 56175:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174].

Props costdev, audrasjb.
See #58459.

#20 @audrasjb
9 months ago

In 56176:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175].

Props costdev, audrasjb.
See #58459.

#21 @audrasjb
9 months ago

In 56177:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176].

Props costdev, audrasjb.
See #58459.

#23 @audrasjb
9 months ago

In 56178:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177].

Props costdev, audrasjb.
See #58459.

#24 @audrasjb
9 months ago

In 56179:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178].

Props costdev, audrasjb.
See #58459.

#25 @audrasjb
9 months ago

In 56180:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179].

Props costdev, audrasjb.
See #58459.

#27 @audrasjb
9 months ago

In 56191:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180].

Props costdev, audrasjb.
See #58459.

#28 @audrasjb
9 months ago

In 56192:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180], [56191].

Props costdev, audrasjb.
See #58459.

#30 @audrasjb
9 months ago

In 56193:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180], [56191], [56192].

Props costdev, audrasjb.
See #58459.

#31 @audrasjb
9 months ago

In 56194:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180], [56191], [56192], [56193].

Props costdev, audrasjb.
See #58459.

@audrasjb commented on PR #4548:


9 months ago
#32

committed in 56193 and 56194

#33 @audrasjb
9 months ago

In 56195:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180], [56191], [56192], [56193], [56194].

Props costdev, audrasjb.
See #58459.

#34 @audrasjb
9 months ago

In 56196:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180], [56191], [56192], [56193], [56194], [56195].

Props costdev, audrasjb.
See #58459.

#36 @audrasjb
9 months ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

And that's a wrap for WP 6.3!
Phew, what a journey or review/refresh/commit :D

Thanks for the patches @costdev :D

#37 @costdev
9 months ago

Thanks @audrasjb! At least any future ones should be reduced! xD

#38 @audrasjb
9 months ago

Sure thing! 🤙

Note: See TracTickets for help on using tickets.