WordPress.org

Make WordPress Core

Opened 10 months ago

Closed 8 months ago

#52025 closed defect (bug) (fixed)

Coding Standards: Single-Line Code Comment Format Used In Place Of Multi-Line Format.

Reported by: pinkalbeladiya Owned by: SergeyBiryukov
Milestone: 5.7 Priority: normal
Severity: normal Version:
Component: Media Keywords:
Focuses: docs, coding-standards Cc:

Description

Wordpress have a comment structure. In the file developer use the single line comment structure. Replace it with the wordpress comment structure.

Attachments (1)

class-wp-media-list-table.png (5.7 KB) - added by pinkalbeladiya 10 months ago.
wp-admin\includes\class-wp-media-list-table

Download all attachments as: .zip

Change History (11)

@pinkalbeladiya
10 months ago

wp-admin\includes\class-wp-media-list-table

#1 @mukesh27
10 months ago

  • Component changed from General to Comments
  • Keywords needs-patch added; has-patch removed
  • Version 5.6 deleted

#2 follow-up: @davidbaumwald
9 months ago

  • Component changed from Comments to Media
  • Focuses docs coding-standards added
  • Keywords reporter-feedback added; needs-patch removed

@mukesh27 I actually think this is not in the Comments component, and the ticket might be titled inaccurately. It seems this ticket concerns a code comment block on line 74 in wp-admin/includes/class-wp-media-list-table.php.

@pinkalbeladiya Can you confirm this is still an issue in version 5.6? I took a look at the code comment in your screenshot, but there appears to be no formatting problems in the most recent version.

#3 in reply to: ↑ 2 @pinkalbeladiya
9 months ago

@mukesh27 Yes, This is in wordpress 5.6. See the link https://prnt.sc/w3053l
Replying to davidbaumwald:

@mukesh27 I actually think this is not in the Comments component, and the ticket might be titled inaccurately. It seems this ticket concerns a code comment block on line 74 in wp-admin/includes/class-wp-media-list-table.php.

@pinkalbeladiya Can you confirm this is still an issue in version 5.6? I took a look at the code comment in your screenshot, but there appears to be no formatting problems in the most recent version.

#4 follow-up: @davidbaumwald
9 months ago

@pinkalbeladiya Can you describe the issue/problem with the comment? I've read the comment a few times, but I'm not seeing an issue with the formatting of it.

#5 in reply to: ↑ 4 @pinkalbeladiya
9 months ago

I think the format of comment is:
/*
*
*
*
*/

And there is used sigle line comment.

Replying to davidbaumwald:

@pinkalbeladiya Can you describe the issue/problem with the comment? I've read the comment a few times, but I'm not seeing an issue with the formatting of it.

#6 follow-up: @davidbaumwald
9 months ago

  • Keywords close added; reporter-feedback removed

@pinkalbeladiya Thanks for the additional context! I actually don't think this is an issue. Running some REGEX on the source, there are thousands of instances of the single-line comment style being used for multi-line comments. Also, there doesn't appear to be any rule in the PHP Coding Standards that forbids code comments in this format.

Tagging this as close for now.

#7 @davidbaumwald
9 months ago

  • Summary changed from Comment Error to Coding Standards: Single-Line Code Comment Format Used In Place Of Multi-Line Format.

#8 @Mista-Flo
8 months ago

  • Resolution set to wontfix
  • Status changed from new to closed

#9 in reply to: ↑ 6 @SergeyBiryukov
8 months ago

  • Keywords close removed
  • Milestone changed from Awaiting Review to 5.7
  • Resolution wontfix deleted
  • Status changed from closed to reopened

Replying to davidbaumwald:

Running some REGEX on the source, there are thousands of instances of the single-line comment style being used for multi-line comments. Also, there doesn't appear to be any rule in the PHP Coding Standards that forbids code comments in this format.

There is a section in the documentation standards that clarifies which format is generally recommended.

This was previously corrected for other inline comments in core in [47122]. I think I opted to keep comments with one or two lines in single line format, and switch comments with three or more lines to the multi-line format.

It looks like this is the only instance introduced since then that's not in an external library, so we might as well fix it :)

#10 @SergeyBiryukov
8 months ago

  • Owner set to SergeyBiryukov
  • Resolution set to fixed
  • Status changed from reopened to closed

In 50071:

Docs: Switch a comment in WP_Media_List_Table::prepare_items() to multi-line format, per the documentation standards.

Follow-up to [48417].

Props pinkalbeladiya, davidbaumwald.
Fixes #52025.

Note: See TracTickets for help on using tickets.