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

[birgire]

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, 
);

[birgire]

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

[birgire]

Adjusted the category-template.php default arguments

[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?

[swissspidy]

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]

Updated patch with DocBlock fixes

[swissspidy]

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.