[wp-trac] [WordPress Trac] #64265: Twenty Twenty-Five: Remove redundant inline comments from functions.php

[WordPress Trac]

#64265: Twenty Twenty-Five: Remove redundant inline comments from functions.php
-----------------------------+-----------------------------
 Reporter:  huzaifaalmesbah  |      Owner:  (none)
     Type:  defect (bug)     |     Status:  new
 Priority:  normal           |  Milestone:  Awaiting Review
Component:  Bundled Theme    |    Version:
 Severity:  normal           |   Keywords:
  Focuses:                   |
-----------------------------+-----------------------------
 = Summary =

 The Twenty Twenty-Five theme's `functions.php` file contains redundant
 inline comments that duplicate the information already present in the
 DocBlock summaries directly below them. According to the
 [https://developer.wordpress.org/coding-standards/inline-documentation-
 standards/php/ WordPress PHP Documentation Standards], this creates
 unnecessary duplication and violates documentation best practices.

 = Problem =

 There are '''7 redundant inline comments''' in `src/wp-
 content/themes/twentytwentyfive/functions.php`:

  * Line 12: `// Adds theme support for post formats.`
  * Line 27: `// Enqueues editor-style.css in the editors.`
  * Line 42: `// Enqueues the theme stylesheet on the front.`
  * Line 70: `// Registers custom block styles.`
  * Line 99: `// Registers pattern categories.`
  * Line 129: `// Registers block binding sources.`
  * Line 150: `// Registers block binding callback function for the post
 format name.`

 Each of these comments immediately precedes a function with a DocBlock
 that contains the exact same information.

 '''Example of redundancy:'''
 {{{
 #!php
 <?php
 // Adds theme support for post formats.
 if ( ! function_exists( 'twentytwentyfive_post_format_setup' ) ) :
         /**
          * Adds theme support for post formats.
          *
          * @since Twenty Twenty-Five 1.0
          *
          * @return void
          */
         function twentytwentyfive_post_format_setup() {
                 // Function implementation
         }
 endif;
 }}}

 = Solution =

 Remove all 7 redundant inline comments. The DocBlocks already provide
 comprehensive documentation for each function, making these inline
 comments unnecessary.

 '''After fix:'''
 {{{
 #!php
 <?php
 if ( ! function_exists( 'twentytwentyfive_post_format_setup' ) ) :
         /**
          * Adds theme support for post formats.
          *
          * @since Twenty Twenty-Five 1.0
          *
          * @return void
          */
         function twentytwentyfive_post_format_setup() {
                 // Function implementation
         }
 endif;
 }}}

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64265>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform