tag:blogger.com,1999:blog-7449668645955818675.post5254478430844859534..comments2022-04-07T01:44:11.758+02:00Comments on Patrick Allaert's Blog about Free Software: Readable PHP code #2 Make your API handle more!Patrick Allaerthttp://www.blogger.com/profile/08540817341697816823noreply@blogger.comBlogger3125tag:blogger.com,1999:blog-7449668645955818675.post-51984132874460589342010-06-16T07:27:39.573+02:002010-06-16T07:27:39.573+02:00Patrick, I actually found your array casting solut...Patrick, I actually found your array casting solution solution very elegant. In my case, handling whatever the user decided to pass in was very important, because our API had to be easy to use. I would up jumping through a number of hoops and did a lot of type checking to make sure we achieved our goal. <br /><br />Great little piece of advice!Chris Henryhttp://chr.ishenry.comnoreply@blogger.comtag:blogger.com,1999:blog-7449668645955818675.post-36564170646409375032010-06-02T19:14:18.188+02:002010-06-02T19:14:18.188+02:00@Artem,
Don't take me wrong, there is is no s...@Artem,<br /><br />Don't take me wrong, there is is no such thing as an absolute rule which forces every method to accept more than one element. This should be applied where it <b>makes sense</b> only!<br /><br />Taking your example into account:<br />public function addContact($contact, $sendWelcomeEmail = false)<br />might simply be:<br />public function addContacts($contacts, $sendWelcomeEmail = false)<br /><br />Where $contacts can be one or more contacts and $sendWelcomeEmail would be a single boolean for the whole list of contacts.<br /><br />If this boolean would be different for every contacts, then nothing prevents you from using it one by one:<br />foreach ($contacts as $contact) {<br /> $user->addContacts($contact, /* bool */);<br />}<br /><br />At least, you have the <b>choice</b>!<br /><br />Type hinting is indeed not directly possible although you have a few alternatives:<br />* Define a ContactIterator which you will use as type hinting.<br />* Handling the type yourself.<br /><br />I don't agree with you saying it is harder to read, check for yourself at: http://pallaert.pastebin.com/i9AXxqSr<br /><br />Having two methods to achieve almost the same thing is the best way to confuse people, check http://chaos.troll.no/~shausman/api-design/api-design.pdf for the characteristics of Good APIs.<br /><br />Of course there is nothing wrong doing a loop! But I assure you that API's supporting bulk operation when it makes sense are sometimes much easier to read/use, performs better or even both.<br /><br />Similarly, which one of the following set of shell commands do you consider more readable?<br />$ for file in *.txt ; do rm $file ; done<br />or:<br />$ rm *.txt<br /><br />I will insist again, apply this where it <b>make sense</b>!Patrick Allaerthttps://www.blogger.com/profile/08540817341697816823noreply@blogger.comtag:blogger.com,1999:blog-7449668645955818675.post-83456861122562801342010-05-28T18:50:25.914+02:002010-05-28T18:50:25.914+02:00I disagree. Strongly.
If your addContact() method...I disagree. Strongly.<br /><br />If your addContact() method needs more parameters, how do you handle that? Example:<br /><br />public function addContact($contact, $sendWelcomeEmail=false);<br /><br />Now you need to pass the boolean into each element of your array. Ugly.<br /><br />What if your method uses type hinting to accept a data access object?<br /><br />public function addContact(UsersTable $user, $sendWelcomeEmail=false);<br /><br />In the simplest of scenarios, maybe, your recommendation holds water. In the real world it breaks semantics, makes things harder to understand and unnecessarily makes the code more obscure and unreadable.<br /><br />If you want to support an array entries, just add another method like this:<br /><br />addMultipleContacts(array $contacts, $sendWelcomeEmail=false);<br /><br />Just because it's less code doesn't make it better. Sometimes verbosity and being explicit <b>is a good thing</b>. There's absolutely nothing wrong with looping and adding a contact on each iteration. Nothing at all.Artem Nezviginhttp://artnez.com/noreply@blogger.com