Agreed completely about how awful dynamic languages can be in this respect. I've found what helps a lot is consistent naming of parameters. For example, numberOfWidgets (an integer) versus widgets (a collection) or file (a file handle) versus path (a string).
Sure, consistent naming helps a lot (though I'm partial to short-yet-readable alternative like widgetCounts). Sadly, sometimes ambiguity is unavoidable. And other times, you're just dealing with bad code.
But consistent naming does not help with the "optionality" of parameters.
Re:The Code Documentation Fallacy
by acjohnson55 on Friday October 18, 2013 @01:08AM
(#6569870)
In that sense, dynamic languages often have a jump on their functional counterparts. Relying on the type annotations for all documentation is probably the other side of the coin. I understand that generic combinators sometimes need sufficiently general argument names, but even then, there's often some semantic meaning that can be attached with a self-documenting variable name. Enough with the 1- and 2-letter variable names!
It's JavaScript, they're all optional.
Just start passing a single object parameter or using the arguments object and force everything into the documentation. Then it'll be just like 90% of libraries that depend on jQuery, especially once the code has been patched, updated, and maintained a year beyond the documentation.
I've now started to document public functions. As my classes usually have few public functions, but many private ones, the code to comment ratio remains acceptable, though maintaining the documentation remains a challenge.