

The Most Important Language Feature No One Talks About - WrongBot
http://wrongbot.com/index.php?option=com_content&view=article&id=7:the-most-important-language-feature-no-one-talks-about&catid=11:languages&Itemid=8

======
raganwald
I agree with the proposition that documentation for available libraries is
extremely important. However--isn't there always a "however..." when someone
starts by agreeing with the thesis?--anyways, however...

Before I start saying "The most important," I think of a story allegedly about
Winston Churchill. At a party, a dowager rebuked him for his inebriation:
"Winston , you are disgracefully drunk!"

He steadied himself and glared at her: "And you, Madam, are ugly. But in the
morning, I shall be sober."

My clumsy point being, you can write libraries for a good language. You can
document them. If the documentation is missing, someone can and eventually
will write it. And _anyone_ can write documentation, just like anyone can
write a library. No committees. No endless blog posts debating how the fourth
paragraph's third word should be capitalized.

But fundamental language features simply cannot be bolted on. Even if they fit
with the language's philosophy and implementation, it is a tremendous
investment to get a new feature added to a language.

Some languages do not admit new features easily. Type erasure, anyone? Some
cultures do not admit new features easily. Closures, anyone? Both are examples
of places where Java couldn't or wouldn't add features cleanly.

There is no such issue with documentation. Anyone can document something, and
everyone should. You don't need to make it official, either. Blog about a
feature or library, and thanks to Google your blog post becomes an ipso facto
part of the library's documentation.

For my money, the measure of a library's documentation is whether I can type
the name of a library into Google and find the answer to my questions on the
top half of the first page.

~~~
garnet7
> If the documentation is missing, someone can and eventually will write it.
> ...

> There is no such issue with documentation. Anyone can document something,

Well, in practice, I think it's more like: if the library is there but the
docs are not, you're going to be pretty hard pressed to find someone willing
to come along, pore over the code, read the mind of the person who wrote the
library, and carefully document it. It's very laborious.

------
gaius
Ermm, _everyone_ talks about the importance of libraries. People have been
whinging about Lisp's "lack" of libraries since the 1970s!

~~~
10ren
He's not exposited it well, but he's saying the _documentation_ of the
libraries is more important than the libraries themselves [middle, 4th
paragraph].

It's an interesting point, like saying that advertising of a product is more
important than the product itself. Sounds ridiculous, doesn't it?

But if you don't know about the product, or what it can do, or how it can be
used - it is of _0_ use to you. It might as well not exist. No matter how
great it is nor how much its creators know about it...

~~~
pavlov
Personally I find that the sample code is often the most important part of the
library. I like to learn by doing, and rewriting sample code into my own style
is a great way to do that.

It needs to be supported by high-quality documentation, of course - preferably
there should be a walkthrough of the code with relevant documentation links
that go into more detail to explain the thinking behind the library.

What I really hate is documentation that's obviously written by technical
writers who understand the concepts in the abstract, but have never written
any code using it. It's frustrating to wade through pages and pages of
patronizing explanations when a real-world example would do the job so much
better.

(The worst example of this documentation genre I've ever seen is probably
Symbian's C++ API documentation. First they spend an eternity justifying their
pseudo-Hungarian type naming convention. Then they introduce a class hierarchy
of a dozen classes for basic buffers and strings, dither over all the
irrelevant details of the implementation, and claim that it's an "elegant
example of object-oriented design". I guess they expect their audience to be
of the captive kind that is forced to sit in a class room for a few weeks
listening to trivialities, so it makes sense to waste all that time going over
outdated '90s buzzwords.)

~~~
aaronblohowiak
Good documentation _includes_ examples. That's why `man` pages have an
EXAMPLES section. The point you seem to be making about documentation
organization being driven practically instead of horn-tooting, I completely
agree with.

~~~
pavlov
Sorry if my point was so unclear. I agree completely that examples are an
integral part of documentation. But it sometimes seems that this point is lost
on the programmers and tech writers who should be collaborating to produce the
documentation (or perhaps management is to blame for treating these roles too
separately).

The result is often documentation that's too verbose, too rigidly structured
according to the implementation's hierarchies and doesn't match the thought
processes and expectations of the target users.

~~~
aaronblohowiak
Right, and I was similarly unclear. I think that examples should be interwoven
with the documentation, and I think that your insights into the systematic
reasons for this are spot-on.

------
Xixi
Documentation is one of the main reasons we are using Django at my startup now
: the documentation is absolutely awesome.

On the other hand I remember doing lots of Erlang/OTP two years ago (failed
startup that never launched...). Equipped with "Programming Erlang" by Joe
Armstrong, and Google of course.

Brilliant book, and lots of documentation available for Erlang. But when it
came to the real thing, OTP, its best pratices and idioms, it was much harder
to find anything relevant at all.

~~~
garnet7
[Werkzeug](<http://werkzeug.pocoo.org/>) also seems to have good docs.

------
DanielStraight
Part of the reason Java's documentation is so "good" is that it needs to be.
If you want to know the length of an array, it's .length (carefully avoiding
parenthesis), for a Vector, it's .size(). For Vector's, there's also
.capacity() which is different from size. Then there's setSize() and
trimToSize(), one of which affects size (and capacity) and one of which just
affects capacity. Then you have ensureCapacity() and isEmpty() which do things
you could easily check on your own.

In Python, the way to tell how long anything is is the len() function. There
is no concept of capacity because there's no reason to care. If you want to
check if a list is empty, you just say "if list_variable". Once you learn
those two basic concepts, which apply to the entire Python library, you never
need to look at documentation for sizes and capacities of anything again.

Python's slice notation replaces an overloaded add(), elementAt(),
firstElement(), get(), insertElementAt(), lastElement(), remove(),
removeAllElements(), removeElement(), removeRange(), set(), setElementAt(),
and subList(). And it works the same for all list-like objects in Python.
Java's copious documentation on those functions (some of which are exact
duplicates) is not a good thing. It's a sign of a serious design problem.

~~~
cmars232
I wish Java would adopt len() and the like. Or perhaps a more general concept
like Haskell's type classes.

------
dkersten
Libraries are extremely important and the major resistance for me to learn
more interesting languages (Eg, I wanted to start using a Lisp, but found
their lack of extensive, well documented libraries to be a hindrance (I have
since started using Clojure, which doesn't have this issue); also wanted to
start using Factor for real projects and I needed libraries which it doesn't
yet have and I don't have time to contribute..)

But I don't find Java to be as good as the article makes it out to be. The
library, IMHO, is a mess and the javadoc documentation, while great most of
the time, sometimes just doesn't explain what you need (like when I had to
learn JAIN from the Javadoc alone...), personally, I find Pythons library just
as extensive and better organised and designed. Seems that documentation is a
matter of taste though - I really like Pythons docs. I find them clear, to the
point and intuitive, but I've also heard people complain about them. I
definitely do agree that libraries with good documentation are important.

~~~
10ren
I was surprised to find that the lack of static types in python made the
documentation less clear for me. I had to read through the documentation to
get a grasp of what the formal parameters meant (e.g. were they strings, or
more complex data structures), and with several parameters, I kept forgetting
which was which. I think there are conventions that experienced python
programmers would pick up (e.g. in the naming of parameters). but I didn't
know them. Sort of, informal static typing, no?

In Java, the types of parameters give succinct guidance (though I hadn't
appreciated this til I saw python docs). You can follow the hyperlinks to get
the definitions.

In Haskell, people claim that its more expressive type-system enables you to
quickly search for relevant functions, without knowing their names. (I can't
verify this personally).

For me, it's very much an unexpected benefit of static type systems.

PS: I don't think Python users need the reassurance, but the actual library
being explained by the docs was a _lot_ simpler and easier to use than the
equivalent in Java.

~~~
loup-vaillant
In Haskell, what you are talking about sounds like type-based search. Like, if
you know you're looking for a function of type `[Int] -> Int`, you probably
want `sum` or `product` (which are of the compatible type `Num n => [n] ->
n`). Am I right?

My first guess is that this kind of search is possible in other languages, yet
easier and more accurate in Haskell and ML because their type system is
paranoid, not because it is expressive.

~~~
jerf
[http://www.haskell.org/hoogle/?hoogle=[Int]+->+Int](http://www.haskell.org/hoogle/?hoogle=\[Int\]+->+Int)

Unrelated to that link: "Paranoid" and "expressive" are... hard to relate to
each other. I certainly can't call them opposing forces in type signatures.
It's a more complicated relationship. Type signatures that can carry lots of
information can be both very "paranoid" (excluding many possibilities) while
at the same time being very expressive (permitting many possibilities). In
English that doesn't make much sense, but it makes perfect sense in the
context of something like Haskell's type system, or other similarly carefully-
crafted ones.

~~~
10ren
That's a startlingly awesome search engine, especially in its suggestions
("did you mean: ").

[http://www.haskell.org/hoogle/?hoogle=[a]+->+maybe+a](http://www.haskell.org/hoogle/?hoogle=\[a\]+->+maybe+a)

But it seems to suggest many non-exact matches, like google does. Useful in a
search engine, but not for seeking an exact function - though I guess it
doesn't hurt to have too many results, provided the exact ones are always
first. (I don't know enough Haskell to be certain)

------
Tichy
So true - unfortunately Java is still the best language in that respect, and
Ruby falls flat big time.

~~~
ntoshev
Java and all the JVM languages. Is it really a _language_ feature?

~~~
Tichy
I don't think it extends to the languages, because that would include jRuby.

I think it is probably because Java was endorsed by a big company that wanted
to market it.

------
cmars232
It's not just that libraries are important. Platforms that are mature,
portable and reliable can get products developed more quickly. Platforms that
run on multiple target OSes improve my deployment options.

It's not just lack of libraries that can hinder a language. An immature
runtime, or one with platform-specific issues limits your options. I think
many more man-hours go into developing a rock-solid runtime library than
language developers / advocates might suspect.

Language is nice to have, platform wins.

