WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 5 years ago

#34751 closed enhancement (fixed)

Improve the readability of the default arguments of the wp_list_categories()

Reported by: birgire Owned by: swissspidy
Milestone: 4.5 Priority: normal
Severity: normal Version: 4.4
Component: Taxonomy Keywords: has-patch commit
Focuses: Cc:

Description

When skimming through the defaults arguments of some core functions, it's easy to miss some attributes, because there are multiple arguments per line.

Here's an example how the default arguments of the wp_list_categories() are written out:

$defaults = array(
	'show_option_all' => '', 'show_option_none' => __('No categories'),
	'orderby' => 'name', 'order' => 'ASC',
	'style' => 'list',
	'show_count' => 0, 'hide_empty' => 1,
	'use_desc_for_title' => 1, 'child_of' => 0,
	'feed' => '', 'feed_type' => '',
	'feed_image' => '', 'exclude' => '',
	'exclude_tree' => '', 'current_category' => 0,
	'hierarchical' => true, 'title_li' => __( 'Categories' ),
	'hide_title_if_empty' => false,
	'echo' => 1, 'depth' => 0,
	'separator' => '<br />',
	'taxonomy' => 'category'
);

I think it would improve readability if we only had a single argument per line:

$defaults = array(
	'show_option_all' => '', 
	'show_option_none' => __('No categories'),
	'orderby' => 'name', 
	'order' => 'ASC',
	'style' => 'list',
	'show_count' => 0, 
	'hide_empty' => 1,
	'use_desc_for_title' => 1, 
	'child_of' => 0,
	'feed' => '', 
	'feed_type' => '',
	'feed_image' => '', 
	'exclude' => '',
	'exclude_tree' => '', 
	'current_category' => 0,
	'hierarchical' => true, 
	'title_li' => __( 'Categories' ),
	'hide_title_if_empty' => false,
	'echo' => 1, 'depth' => 0,
	'separator' => '<br />',
	'taxonomy' => 'category'
);

Even better to have it alphabetically ordered:

$defaults = array(
	'child_of' => 0,
	'current_category' => 0,
	'depth' => 0,
	'echo' => 1, 
	'exclude' => '',
	'exclude_tree' => '', 
	'feed' => '', 
	'feed_type' => '',
	'feed_image' => '', 
	'hide_empty' => 1,
	'hide_title_if_empty' => false,
	'hierarchical' => true, 
	'orderby' => 'name', 
	'order' => 'ASC',
	'show_option_all' => '', 
	'show_option_none' => __('No categories'),
	'style' => 'list',
	'show_count' => 0, 
	'separator' => '<br />',
	'taxonomy' => 'category'
	'title_li' => __( 'Categories' ),
	'use_desc_for_title' => 1, 
);

I actually prefer this:

$defaults = array(
	'child_of'            => 0,
	'current_category'    => 0,
	'depth'               => 0,
	'echo'                => 1, 
	'exclude'             => '',
	'exclude_tree'        => '', 
	'feed'                => '', 
	'feed_type'           => '',
	'feed_image'          => '', 
	'hide_empty'          => 1,
	'hide_title_if_empty' => false,
	'hierarchical'        => true, 
	'orderby'             => 'name', 
	'order'               => 'ASC',
	'show_option_all'     => '', 
	'show_option_none'    => __('No categories'),
	'style'               => 'list',
	'show_count'          => 0, 
	'separator'           => '<br />',
	'taxonomy'            => 'category'
	'title_li'            => __( 'Categories' ),
	'use_desc_for_title'  => 1, 
);

Attachments (2)

34751.diff (1.5 KB) - added by birgire 5 years ago.
Adjusted the category-template.php default arguments
34751.2.diff (2.1 KB) - added by swissspidy 5 years ago.
Updated patch with DocBlock fixes

Download all attachments as: .zip

Change History (8)

#1 @birgire
5 years ago

ps: my alphabetical ordering above can be improved ;-)

Last edited 5 years ago by birgire (previous) (diff)

@birgire
5 years ago

Adjusted the category-template.php default arguments

#2 @birgire
5 years ago

  • Keywords has-patch added

#3 @swissspidy
5 years ago

  • Component changed from General to Taxonomy
  • Keywords commit added
  • Milestone changed from Awaiting Review to 4.5

#4 follow-up: @birgire
5 years ago

ps: there are tons of similar adjustments possible in the core.

I could add the patches under this current ticket (I guess we would need to change the title?) or I could just create another ticket to combine them all?


#5 in reply to: ↑ 4 @swissspidy
5 years ago

Replying to birgire:

ps: there are tons of similar adjustments possible in the core.

I could add the patches under this current ticket (I guess we would need to change the title?) or I could just create another ticket to combine them all?

I totally believe that there are tons of similar "bugs" in the code base. If you find any other areas where it definitely makes sense to improve readability / documentation, feel free to open another ticket.

Just note that we don't refactor just for the sake of refactoring: https://make.wordpress.org/core/2011/03/23/code-refactoring/.

wp_list_categories() stands out because there are lots of arguments which are hard to read and not all of them are properly documented in the function's DocBlock (see [35140]).

@swissspidy
5 years ago

Updated patch with DocBlock fixes

#6 @swissspidy
5 years ago

  • Owner set to swissspidy
  • Resolution set to fixed
  • Status changed from new to closed

In 36135:

Docs: Improve readability of the default arguments of wp_list_categories().

Adds missing documentation for the separator argument introduced in [35140].

Props birgire for initial patch.
Fixes #34751.

Note: See TracTickets for help on using tickets.