Function naming is hard (even PHP-FIG gets it wrong)


Craft, Programming, Uncategorized / Friday, October 26th, 2018

There’s a famous saying that two of the hardest problems in computer science are cache invalidation and naming things. When it comes to defining standards, there’s no cache involved, but there is a lot of naming of things. It should come as no surprise, but I recently was shocked to see that the folks who create standards (with all the time in the world?) are too human.

Consider the case of the MessageInterface for HTTP requests, as developed and released by the PHP Framework Interoperability Group (PHP-FIG). In particular, I want to highlight the method withHeader().

Just in case this changes by the time you’re reading this (highly unlikely), here’s the code reproduced:

 
 
    /**
     * Return an instance with the provided value replacing the specified header.
     *
     * While header names are case-insensitive, the casing of the header will
     * be preserved by this function, and returned from getHeaders().
     *
     * This method MUST be implemented in such a way as to retain the
     * immutability of the message, and MUST return an instance that has the
     * new and/or updated header and value.
     *
     * @param string $name Case-insensitive header field name.
     * @param string|string[] $value Header value(s).
     * @return static
     * @throws \InvalidArgumentException for invalid header names or values.
     */
    public function withHeader($name, $value);

I couldn’t believe my eyes when I first read this. A function named withHeader actually replaces the given header line and returns the Message instance! Oh my fucking God! 😱 😱 😱

I immediately thought, “Really?! Was is that hard to come up with something like withReplacedHeader()?” And it’s not like the rest of the code makes similar oversights. Right next to it is another function signature:

 
 
    /**
     * Return an instance with the specified header appended with the given value.
     *
     * Existing values for the specified header will be maintained. The new
     * value(s) will be appended to the existing list. If the header did not
     * exist previously, it will be added.
     *
     * This method MUST be implemented in such a way as to retain the
     * immutability of the message, and MUST return an instance that has the
     * new header and/or value.
     *
     * @param string $name Case-insensitive header field name to add.
     * @param string|string[] $value Header value(s).
     * @return static
     * @throws \InvalidArgumentException for invalid header names or values.
     */
    public function withAddedHeader($name, $value);

This time the function is named withAddedHeader() and does exactly that: returns an instance of the Message with an additional header added.

My guess is that withHeader() got overlooked in the code review process, and by the time it was detected, the PHP-FIG’s HTTP Message standard was out and implemented by millions of libraries and frameworks. Oops!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.