The Most Important Language Feature No One Talks About(wrongbot.com)
wrongbot.com
The Most Important Language Feature No One Talks About
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
8 comments
> 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.
> 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.
Ermm, everyone talks about the importance of libraries. People have been whinging about Lisp's "lack" of libraries since the 1970s!
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...
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...
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.)
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.)
I agree completely, and this is what I _dislike_ the most about Java libraries. Far too much Java code that I've seen has relied entirely on what Javadoc can produce automatically from a codebase that does not contain lots of hints and extra documentation. A listing of classes and their methods is not even an adequate reference guide, let alone an adequate explanation of how to use the library and why it was written the way it was.
As a counter example, I find that most perldoc documentation on CPAN is pretty good, because the standard practice for Perl module documentation is centered on the documentation sections that should be included _other than the list of methods_. NAME, SYNOPSIS, DESCRIPTION, USAGE, AUTHOR, SEE ALSO are all standard sections, and the kind of stuff that javadoc normally generates is just a subset of USAGE.
As a counter example, I find that most perldoc documentation on CPAN is pretty good, because the standard practice for Perl module documentation is centered on the documentation sections that should be included _other than the list of methods_. NAME, SYNOPSIS, DESCRIPTION, USAGE, AUTHOR, SEE ALSO are all standard sections, and the kind of stuff that javadoc normally generates is just a subset of USAGE.
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.
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.
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.
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.
>>Good documentation includes examples.
Should be: Good documentation includes good examples. Most example code out there is the worst code I have ever seen. Typically it looks like something someone slapped together in 5 min. Removing error handling to "improve clarity" just means that there are no examples of what errors the author of the library actually thinks are important or how to recover from recoverable errors.
It is not an interesting point. It is merely a literary 'trick'.
It is just unconscious use of the rhetorical form 'paradox': it says something apparently nonsensical in order to capture attention, perhaps to express a related truth. The way to handle rhetoric is to recognise it and not be diverted by it, and look if anything substantial is actually being said.
I am not saying it is delibarate, and deceptive; it is more like a cliche -- it can happen accidently in writing something.
Saying "documentation is more important than library" really is nonsense. If you had one but not the other, which would you choose? If you have only the library, you can probably figure out how to use some parts. If you have only docs, you have nothing working at all.
The point of course is: documentation is important. Almost certainly very true. Though it now seems rather mundane. The best treatment for such a situation is not to follow some rhetorical flow, but to search for something more interesting to say. Or just say it simply, express a little enjoyment maybe, and have a brief blog post.
It is just unconscious use of the rhetorical form 'paradox': it says something apparently nonsensical in order to capture attention, perhaps to express a related truth. The way to handle rhetoric is to recognise it and not be diverted by it, and look if anything substantial is actually being said.
I am not saying it is delibarate, and deceptive; it is more like a cliche -- it can happen accidently in writing something.
Saying "documentation is more important than library" really is nonsense. If you had one but not the other, which would you choose? If you have only the library, you can probably figure out how to use some parts. If you have only docs, you have nothing working at all.
The point of course is: documentation is important. Almost certainly very true. Though it now seems rather mundane. The best treatment for such a situation is not to follow some rhetorical flow, but to search for something more interesting to say. Or just say it simply, express a little enjoyment maybe, and have a brief blog post.
Documentation is more important than the library, in terms of quality. Obviously you need the one before you can have the other, but I'd take a slow and slightly buggy library that I know how to use over a more functional one that I'll never figure out.
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.
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.
[Werkzeug](http://werkzeug.pocoo.org/) also seems to have good docs.
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.
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.
I wish Java would adopt len() and the like. Or perhaps a more general concept like Haskell's type classes.
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.
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.
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.
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.
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.
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.
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.
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.
That's a startlingly awesome search engine, especially in its suggestions ("did you mean: ").
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)
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)
That seems right, though I was thinking more of alternate ("union"?) types, like `A -> A | null`. That's the expressive part.
(nb: I'm not a Haskell user, so my syntax aims to be more suggestive than correct. I only know about it from some paper I came across).
But you're right you could do that example in Java (4eg): int xxxxx(int[] x)
(nb: I'm not a Haskell user, so my syntax aims to be more suggestive than correct. I only know about it from some paper I came across).
But you're right you could do that example in Java (4eg): int xxxxx(int[] x)
In Haskell, what you call a union type is more often called "sum type", or "tagged union". You declare them this way (your syntax was quite good):
data IntOrNothing = AnInteger Int
| Nothing
test :: IntOrNothing -> bool -- optional type declaration
test AnInteger i -> True
test Nothing -> False
test :: IntOrNothing -> bool -- optional type declaration
test intOrNot = case intOrNot of
AnInteger i -> True
Nothing -> False
Thats a good point, actually. If Pythons docs gave better type information for the parameters, then this would be solved..
So true - unfortunately Java is still the best language in that respect, and Ruby falls flat big time.
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.
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.
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.