One of the best advice I got was "Code is written once but read many times".
This particularly holds for public API and thus I often compromise
more on the readability side rather than code size or verbosity.
Beside Garrett's example, my favorite classic of the so-called
"Boolean trap" is:
foobar.repaint(true);
Those who read that line of code think that it means "do NOT repaint".
Much to their surprise, the function footprint is
'repaint(immediate)', where immediate is true or false (the latter to
indicate delayed repaint).
In this example, the most common solution I see is to create a
separate function, e.g. deferRepaint, which gets rid of any ambiguity.
For the following case:
contactList.filter('age', 18, true, false);
it's likely tedious to create all combinations of the last two
(optional) arguments and thus easier to handle as:
contactList.filter('age', 18, { anyMatch: true, caseSensitive: false })
While I completely agree that API documentation would help the
programmer when writing down the code, do not forget that often the
code will be read/copied/reused/analyzed/reviewed by his peers and
thus it would be helpful to avoid the lookup of the documentation of
simple API uses.
Just my $0.02.
Thank you!
Best regards,
Ariya
--
To view archived discussions from the original JSMentors Mailman list:
http://www.mail-archive.com/[email protected]/
To search via a non-Google archive, visit here:
http://www.mail-archive.com/[email protected]/
To unsubscribe from this group, send email to
[email protected]
