Hacker News Reader

Comment by mercurial | Hacker News Reader

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.

View on HN

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!

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.

Reply on news.ycombinator.com