WordPress.org

Make WordPress Core

Opened 5 weeks ago

Last modified 4 weeks ago

#44051 new defect (bug)

Improve `WP_Privacy_Policy_Content::get_default_content()` readability

Reported by: desrosj Owned by:
Milestone: 4.9.8 Priority: normal
Severity: normal Version: 4.9.6
Component: Privacy Keywords: has-patch gdpr
Focuses: coding-standards Cc:

Description

The coding standards state "readability is more important than cleverness or brevity."

WP_Privacy_Policy_Content::get_default_content() has lots of $descr && $content .= statements.

This statement adds the string that follows .= to $content if $descr is passed to the function as true.

Replacing these with if ( $descr ) {} is much less clever, but more readable.

Attachments (2)

44051.diff (21.8 KB) - added by desrosj 5 weeks ago.
44051.2.diff (22.4 KB) - added by ovann86 5 weeks ago.
Change argument name from 'descr' to 'include_descriptions' to make it's role easier to understand.

Download all attachments as: .zip

Change History (9)

#1 @desrosj
5 weeks ago

  • Keywords has-patch gdpr added; has-patchg dpr removed

Related: #44048, #44050.

@desrosj
5 weeks ago

#2 @desrosj
5 weeks ago

  • Milestone changed from Awaiting Review to 4.9.7

@ovann86
5 weeks ago

Change argument name from 'descr' to 'include_descriptions' to make it's role easier to understand.

#3 @ovann86
5 weeks ago

I would like to suggest going one step further by changing the variable name from 'descr' to 'include_descriptions' to make its role easier to understand.

Whilst I'm not seeing this in the WordPress PHP coding standards, using full words (instead of abbreviations) that properly describe the variable is seen more often than not in the rest of core.

note: my patch also fixes a typo in the variable's description - from undet to under

Last edited 5 weeks ago by ovann86 (previous) (diff)

#4 @azaozz
5 weeks ago

This follows the pattern from script-loader.php:

did_action( 'init' ) && $scripts->localize()...

Don't think that is really "clever" code, pretty standard pattern for many repeated if ( true ) statements.

Replacing these with if ( $descr ) {} is much less clever, but more readable.

I'm not so sure this makes it more readable. The part that needs to be readable is the text strings rather than the conditionals. Multiple if were the first thing I tried but repeating if ( $descr ) { 20 times felt wrong. Also it makes the strings less readable because of the indentation.

Nevertheless I'm still not happy with the readability there. Maybe we can try something like:

$descr && $content .= '<div class="wp-suggested-text">';
          $content .= '<h2>' . __( 'Who we are' ) . '</h2>';
$descr && $content .= '<p class="privacy-policy-tutorial">' . __( 'In this section you should note your site URL, as well as the name of the company, organization, or individual behind it, and some accurate contact information.' ) . '</p>';
$descr && $content .= '<p class="privacy-policy-tutorial">' . __( 'The amount of information you may be required to show will vary depending on your local or national business regulations. You may, for example, be required to display a physical address, a registered address, or your company registration number.' ) . '</p>';
          $content .= '<p>' . $suggested_text . sprintf( __( 'Our website address is: %s.' ), get_bloginfo( 'url', 'display' ) ) . '</p>';

          $content .= '<h2>' . __( 'What personal data we collect and why we collect it' ) . '</h2>';

#5 @desrosj
5 weeks ago

  • Component changed from General to Privacy

Moving to the new Privacy component.

#6 @desrosj
5 weeks ago

  • Version set to 4.9.6

Marking privacy bugs as introduced in 4.9.6.

#7 @desrosj
4 weeks ago

  • Milestone changed from 4.9.7 to 4.9.8

Moving all tickets in 4.9.7 to 4.9.8.

Note: See TracTickets for help on using tickets.