6 ms·

Go nails code readability and documentation better than any other language I'm aware of. For example, look at the package documentation for Go's list data stru

Go nails code readability and documentation better than any other language I'm aware of. For example, look at the package documentation for Go's list data structure at http://golang.org/pkg/container/list/ http://golang.org/pkg/container/list/. 5 seconds of reading this you immediately get what the package does and how to use it. Now let's say you want to know how the list is implemented. No problemo. Click the package files link list.go, http://golang.org/src/pkg/container/list/list.go http://golang.org/src/pkg/container/list/list.go, and you're presented with very readable source code. Now compare this with Java. I just Google'd Java List. First link is this: http://docs.oracle.com/javase/6/docs/api/java/util/List.html http://docs.oracle.com/javase/6/docs/api/java/util/List.html Documentation looks OK, but wait, this is the interface. I want to see docs for a concrete implementation. I'm tempted to click on the AbstractList link, but oh wait, that's just another non-concrete class that other List classes probably inherit from. Let's see, let's go to the ArrayList ... this looks good. http://docs.oracle.com/javase/6/docs/api/java/util/ArrayList.html http://docs.oracle.com/javase/6/docs/api/java/util/ArrayList... Nice. I wonder how they implemented this. And I'll keep wondering because I can't find a link to the source code. Maybe there is a link to it, maybe not. We're talking about Oracle so without knowing better, I'll assume there is not ... Let's try Scala. Google "Scala List". Click on first link. http://www.scala-lang.org/api/current/index.html#scala.collection.immutable.List http://www.scala-lang.org/api/current/index.html#scala.colle... What the fuh is a "sealed abstract class List[+A] extends AbstractSeq[A] with LinearSeq[A] with Product with GenericTraversableTemplate[A, List] with LinearSeqOptimized[A, List[A]]" Oh sweet, this thing has all kinds of methods, i.e. ++, ++:, +:, /:, :+, ::, :::, :\ Reading further, I see section in the documentation called "Shadowed Implict Value Members". Wow, I have no idea what that is. Looking back to the Go documentation, I immediately "relax" as another commenter put it. For some reason, I think Scala will end up being the next Java. It has so much momentum, runs on the JVM, has seamless interop with Java code. Has the Play Framework, AKKA, and thousands of other awesome libraries written for it. And if Scala powers Twitter, then I think this answers the scalability and concurrency question. While I'm bullish on Scala, at the end of the day, I find Go's simplicity make it more beautiful than any other language.

rorrr 14y ago
> Go nails code [cut] documentation better than any other language I'm aware of. That's because you haven't seen PHP's documentation. Look at your Go's list example. It doesn't even show how to create a list and fill it with items. It doesn't have users' comments. It doesn't explain much about the data structure. Can it be a circular doubly link list, for instance? Is there a method to empty the list, or quickly insert more than one element? Instead it has strangely named sections (like "type Element") that aren't obvious to somebody new to the language. Sorry, but this documentation is shit.
- enneff 14y ago
  That's a bit harsh. Library docs are for users of the language. I grant that the list package could use more docs (I personally find it a bad example) but for someone who knows Go, all the important stuff is there. Juba surprised that you rate the PHP docs so highly, particularly the user comments. Typically those comments contain terrible advice!
  - rorrr 14y ago
    Users' comments are important to figure out unusual behaviors, bugs, edge cases, to clarify documentation in general, and to add code examples. Of course, some of them will be incorrect and bad advice, that's why I think PHP docs should add up/down voting on each post. More than anything, it creates the sense of community. You always know there are people reading and writing stuff about a specific method, and, most of the time, it's helpful. Considering how bad and inconsistent PHP is, their documentation is amazing.
- codygman 14y ago
  Documentation is for documentation by the people who implement the language and know how it should be best used. User comments on official documentation are likely to have tons of different coding styles, so a new user would pick up a lot of bad habits. If all of the docs are written by go developers/contributors who know that the code in examples should be consistent, then all those bad habits aren't ingrained in new users. Something golang has that I don't know anyone else has is this: http://talks.golang.org/2012/concurrency.slide#1 http://talks.golang.org/2012/concurrency.slide#1 Also another thing about Go, is the source code for each of those packages is extremely easy to understand... it's truly self documenting... there's also the option of looking at the list_test.go file. I will admit a method to empty the list as well as insert more than one element would be nice.

rorrr 14y ago

> Go nails code [cut] documentation better than any other language I'm aware of. That's because you haven't seen PHP's documentation. Look at your Go's list example. It doesn't even show how to create a list and fill it with items. It doesn't have users' comments. It doesn't explain much about the data structure. Can it be a circular doubly link list, for instance? Is there a method to empty the list, or quickly insert more than one element? Instead it has strangely named sections (like "type Element") that aren't obvious to somebody new to the language. Sorry, but this documentation is shit.

enneff 14y ago
That's a bit harsh. Library docs are for users of the language. I grant that the list package could use more docs (I personally find it a bad example) but for someone who knows Go, all the important stuff is there. Juba surprised that you rate the PHP docs so highly, particularly the user comments. Typically those comments contain terrible advice!
- rorrr 14y ago
  Users' comments are important to figure out unusual behaviors, bugs, edge cases, to clarify documentation in general, and to add code examples. Of course, some of them will be incorrect and bad advice, that's why I think PHP docs should add up/down voting on each post. More than anything, it creates the sense of community. You always know there are people reading and writing stuff about a specific method, and, most of the time, it's helpful. Considering how bad and inconsistent PHP is, their documentation is amazing.
codygman 14y ago
Documentation is for documentation by the people who implement the language and know how it should be best used. User comments on official documentation are likely to have tons of different coding styles, so a new user would pick up a lot of bad habits. If all of the docs are written by go developers/contributors who know that the code in examples should be consistent, then all those bad habits aren't ingrained in new users. Something golang has that I don't know anyone else has is this: http://talks.golang.org/2012/concurrency.slide#1 http://talks.golang.org/2012/concurrency.slide#1 Also another thing about Go, is the source code for each of those packages is extremely easy to understand... it's truly self documenting... there's also the option of looking at the list_test.go file. I will admit a method to empty the list as well as insert more than one element would be nice.