On Mon, Aug 24, 2009 at 11:24 AM, Tim Starlingtstarling@wikimedia.org wrote:
I'm afraid your thinking on this is going in precisely the opposite direction to mine. I think long lists of formal parameters make code almost impossible to read and nearly as difficult to write. It might take slightly longer to type
Html::img( array( 'src' => $src, 'alt' => $alt ) );
but at least you can read that, and write it, without having to look up the parameter order in the documentation, and without having to memorise the parameter orders for large numbers of similar functions.
Unless a programmer uses a function regularly, recalling what order the parameters should be in will be a difficult task, requiring several seconds if it's possible at all.
. . .
It would be good if we could have some sort of consensus on this so that we don't end up converting each others' code.
I agree with pretty much everything you've said. I only wish PHP supported named parameters like Python, since PHP's array syntax is pretty ugly. I'll see about removing Html::input(), at least. I'm not sure yet whether HTMLForm is a suitable replacement, since it has essentially no comments and I haven't yet done enough experimentation to figure out how it works . . .
Before being gradually replaced by this starting in MW 1.14:
function link( $target, $text = null, $customAttribs = array(), $query = array(), $options = array() )
which is an unfortunate example of bad design from the outset, since there are 5 formal parameters, 4 of them optional, and a number of callers only override $options. Consider this:
$sk->link( $target, null, array(), array(), array( 'known' ) );
versus this:
$sk->link( $target, array( 'known' => true ) );
and tell me which one is easier to understand and type.
To be fair, $sk->knownLink( $target ) is easier to type than either and no harder to understand, and that's what's used now for this *specific* case. I agree that condensing the options is a good idea, though -- it's rare that any caller uses all five parameters, but many use at least two or three, and often not the first two or three. Something like
$sk->link( $this->mTitle, array( 'text' => wfMsgHtml( 'markaspatrolledtext' ), 'query' => array( 'action' => 'markpatrolled', 'rcid' => $rcid ), 'known', 'noclasses' ) )
isn't very pretty, but it's certainly much more readable. I can't remember the order of the parameters myself, and I wrote them.
It's actually pretty easy in PHP to totally switch over the kind of parameters that a function takes. In the case of link(), we could collapse the last four arguments into an associative array, and use func_get_args() to fall back to the old way if the second argument is a non-array.