Twenty Twenty-Five: Remove redundant inline comments from functions.php

[huzaifaalmesbah]

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 ​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
// 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
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;

[westonruter]

This does seem redundant, but largely harmless.

What specific part of the documentation standards indicate that this is incorrect?

[huzaifaalmesbah]

@westonruter Thanks for reviewing the ticket. This isn’t a functional issue it's really just about keeping DRY (“Don’t Repeat Yourself”). The DocBlock already explains what the function does, so the inline comment is basically repeating the same thing without adding any real value.

Just duplication and doesn’t actually break any documentation rules.

[westonruter]

I can see that the other bundled themes lack such comments for their conditionally-defined functions. So this would make Twenty Twenty-Five consistent.

Do you want to add a patch?

Trac ticket: https://core.trac.wordpress.org/ticket/64265

• Remove the redundant comments for conditionally defined function and make theme consistent with other themes.

[westonruter]

In 61272:

Twenty Twenty-Five: Remove redundant comments for conditionally-defined functions.

This also improves consistency with other themes.

Follow-up to [59146].

Fixes #64265.
See #64226.
Props hbhalodia, huzaifaalmesbah.