I've done plenty of dynamic language work where some documentation would go a long way. In Javascript, every library function should explain what all optional (i.e. undeclared or reinterpreted) parameters do, what gets returned, and likewise for all callbacks, plus `this` points to. It's very stylish for some insane reason not to do this, and it drives me insane.
Don't get me started on Javascript. It's a problem with dynamic languages in general - the signature does not document what interface the parameters should implement (eg, a parameter 'file' may be a file path or a file handle, but you'll only know that by looking at the implementation), but it's particularly egregious when nothing tells you at first glance which parameters are optional.
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.
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.
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!
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 agree. Some Python APIs aren't clear on what the parameters to functions are. It's frustrating to not know what type is even expected - yes, Python is dynamic, and one parameter can take on multiple types, but the documentation should still say which types are allowed, and what the behavior will be.
