[wp-trac] [WordPress Trac] #56648: Improve comment type for Single line comment

[WordPress Trac]

#56648: Improve comment type for Single line comment
------------------------------+-------------------------------
 Reporter:  rajanpanchal2028  |       Owner:  (none)
     Type:  enhancement       |      Status:  closed
 Priority:  low               |   Milestone:
Component:  General           |     Version:
 Severity:  minor             |  Resolution:  invalid
 Keywords:  has-patch         |     Focuses:  coding-standards
------------------------------+-------------------------------

Comment (by jrf):

 Replying to [comment:3 davidbaumwald]:
 > @jrf Thanks for the info!  I also found the
 [https://developer.wordpress.org/coding-standards/inline-documentation-
 standards/php/#3-requires-and-includes 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.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/56648#comment:4>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform