Make WordPress Core

Opened 18 months ago

Closed 18 months ago

Last modified 17 months ago

#56648 closed enhancement (invalid)

Improve comment type for Single line comment

Reported by: rajanpanchal2028's profile rajanpanchal2028 Owned by:
Milestone: Priority: low
Severity: minor Version:
Component: General Keywords: has-patch
Focuses: coding-standards Cc:

Description

I have improved the comment for a single line on the admin-ajax.php file so it should be not / /.

Attachments (1)

56648.patch (1.5 KB) - added by rajanpanchal2028 18 months ago.

Download all attachments as: .zip

Change History (5)

#1 @davidbaumwald
18 months ago

  • Component changed from Comments to General
  • Focuses accessibility template removed
  • Priority changed from normal to low
  • Severity changed from major to minor
  • Version 6.0.2 deleted

There are actually quite a few single-line comments using this style in Core. Actually, there are more even just in admin-ajax.php.

I think it's probably best to address these in bulk(but perhaps one file at a time). We could also add these to the .git-blame-ignore-revs file.

I am cleaning the ticket details up a bit. I'm also unsetting the version for now. This goes back a long time, and I'm not able to quickly fine the exact changeset this traces back to. However, I know it's not the 6.0.2 version.

Finally, @rajanpanchal2028, your patch includes some unrelated changes that I don't think you intended to include.

#2 @jrf
18 months ago

  • Milestone Awaiting Review deleted
  • Resolution set to invalid
  • Status changed from new to closed

Actually... (include|require)[_once] statements are considered structural elements for which a (short-form) docblock is the correct annotation format.

Also see: https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#3-definitions

#3 follow-up: @davidbaumwald
17 months ago

@jrf Thanks for the info! I also found the inline docs standards, and it seems to suggest a docblock, not a comment. I understand that you suggested a short-form docblock, so that may be the same thing. Does Core follow PSR-5 in this instance or WPCS?

Is this something we could add/clarify in the docs for specifically documenting includes?

Also wondering if we should standardize this across the codebase.

For some data, Core is currently a bit inconsistent: (Props to @desrosj for the data here)

  • require* with full DocBlock: 55 (26 within default themes)
  • require* with inline /** comment */: 216
  • No include statements with preceding comment of either style.

#4 in reply to: ↑ 3 @jrf
17 months ago

Replying to davidbaumwald:

@jrf Thanks for the info! I also found the inline docs standards, and it seems to suggest a docblock, not a comment. I understand that you suggested a short-form docblock, so that may be the same thing.

I only mentioned "short-form" docblocks here as that is the format used in the comment which was reported.

Generally speaking, short-form docblocks are not all that commonly used in WP, except for hook documentation when the actual documentation is elsewhere, i.e. /** Hook documented in ... */.

Is this something we could add/clarify in the docs for specifically documenting includes?

Also wondering if we should standardize this across the codebase.

For some data, Core is currently a bit inconsistent: (Props to @desrosj for the data here)

  • require* with full DocBlock: 55 (26 within default themes)
  • require* with inline /** comment */: 216
  • No include statements with preceding comment of either style.

Overhauling and improving the docs standards is on a long-term to-do list of mine.

At this point in time, WP Core does not use the WordPress-Docs standard for PHPCS, so any standardization would involve a lot of manual work, both to fix existing things, as well as to safeguard that new comments/docs comply.

The Docs standard should probably be used, but I'm the first to point out that's it's not that great as it is at this moment and may yield more annoyance and problems than that it solves.

So, for now, I'd leave this until we have a more solid set of base sniffs for documentation in place and the WordPress-Docs standard could actually properly enforce the standards.

Note: See TracTickets for help on using tickets.