7 ms·

The Most Important Language Feature No One Talks About

28 points by WrongBot 17y ago

gaius 17y ago
Ermm, everyone talks about the importance of libraries. People have been whinging about Lisp's "lack" of libraries since the 1970s!
- 10ren 17y ago
  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 17y ago
    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 17y ago
      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 17y ago
        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 17y ago
        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.
      - stonemetal 17y ago
        >>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.
    - DougWebb 17y ago
      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.
  - hxa7241 17y ago
    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.
    - WrongBot 17y ago
      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.
Tichy 17y ago
So true - unfortunately Java is still the best language in that respect, and Ruby falls flat big time.
- ntoshev 17y ago
  Java and all the JVM languages. Is it really a language feature?
  - Tichy 17y ago
    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.
dkersten 17y ago
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 17y ago
  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 17y ago
    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.
Xixi 17y ago
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 17y ago
  [Werkzeug](http://werkzeug.pocoo.org/ http://werkzeug.pocoo.org/) also seems to have good docs.
anonjon 17y ago
Documentation is great, but they main reason you need so much documentation to use Java is that it is a gigantic lumbering monster. There doesn't seem to be a way to arrange Java code so that it is trivially understandable from the source itself (Mostly because of the shoehorning you have to do to fit everything into a class-based programming model). It is surprising to me that in 60+ years of computing, we still aren't writing code that is easily interpretable by both humans and machines. then again, call me a hypocrite, as I hack lisp...
raganwald 17y ago
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 17y ago
  > 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.
DanielStraight 17y ago
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 17y ago
  I wish Java would adopt len() and the like. Or perhaps a more general concept like Haskell's type classes.
cmars232 17y ago
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.

28 points by WrongBot 17y ago

gaius 17y ago

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

10ren 17y ago
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 17y ago
  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 17y ago
    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 17y ago
      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 17y ago
        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.
    - stonemetal 17y ago
      >>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.
  - DougWebb 17y ago
    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.
- hxa7241 17y ago
  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.
  - WrongBot 17y ago
    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.

Tichy 17y ago

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

ntoshev 17y ago
Java and all the JVM languages. Is it really a language feature?
- Tichy 17y ago
  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.

dkersten 17y ago

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 17y ago
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 17y ago
  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.

Xixi 17y ago

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 17y ago
[Werkzeug](http://werkzeug.pocoo.org/ http://werkzeug.pocoo.org/) also seems to have good docs.

anonjon 17y ago

Documentation is great, but they main reason you need so much documentation to use Java is that it is a gigantic lumbering monster. There doesn't seem to be a way to arrange Java code so that it is trivially understandable from the source itself (Mostly because of the shoehorning you have to do to fit everything into a class-based programming model). It is surprising to me that in 60+ years of computing, we still aren't writing code that is easily interpretable by both humans and machines. then again, call me a hypocrite, as I hack lisp...

raganwald 17y ago

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 17y ago
> 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.

DanielStraight 17y ago

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 17y ago
I wish Java would adopt len() and the like. Or perhaps a more general concept like Haskell's type classes.

cmars232 17y ago

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.