3 ms·

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 impl

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.

bookface 13y ago
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).
- mercurial 13y ago
  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.
- acjohnson55 13y ago
  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!
vizeroth 13y ago
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.

bookface 13y ago

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).

mercurial 13y ago
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.
acjohnson55 13y ago
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!

vizeroth 13y ago

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.