[wp-trac] [WordPress Trac] #60247: Replace exclusionary words within code comments

[WordPress Trac]

#60247: Replace exclusionary words within code comments
--------------------------+----------------------------------
 Reporter:  dartiss       |       Owner:  joedolson
     Type:  defect (bug)  |      Status:  accepted
 Priority:  normal        |   Milestone:  6.5
Component:  General       |     Version:
 Severity:  normal        |  Resolution:
 Keywords:                |     Focuses:  accessibility, docs
--------------------------+----------------------------------

Comment (by dmsnell):

 It might be useful to expand the XMLRPC change a bit, as the previous
 language also connoted that the `sleep( 1 )` was something regrettable but
 pragmatic.

 In this wording change we've removed the implicit warning and replaced it
 with a confidence boost in the line of code it's describing -
 communicating that developers shouldn't try to change it.

 Can we find a way to include the original warning but provide a little
 more structure to whoever comes back to this code?

 {{{#!php
 <?php
 /*
  * The remote site may have sent the pingback before it finished
 publishing its own content
  * containing this pingback URL. If that happens then it won't be
 immediately possible to fetch
  * the pinging post; adding a small delay reduces the likelihood of this
 happening.
  *
  * While there are more robust methods than calling `sleep()` here
 (because `sleep()` merely
  * mitigates the risk of requesting the remote post before it's
 available), this is effective
  * enough for most cases and avoids introducing more complexity into this
 code.
  *
  * One way to improve the reliability of this code might be to add
 failure-handling to the remote
  * fetch and retry up to a set number of times if it receives a 404. This
 could also handle 401 and
  * 403 responses to differentiate the "does not exist" failure from the
 "may not access" failure.
  */
 sleep( 1 );
 }}}

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/60247#comment:9>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform