6 ms·

I guess it's hard to get around to the advanced features when so few people even bother to take advantage of the basic ones. Documentation for most Go librarie

I guess it's hard to get around to the advanced features when so few people even bother to take advantage of the basic ones. Documentation for most Go libraries I've come across has been pathetic compared to similar things in Python or PHP. edit: Compare to something like Racket: https://docs.racket-lang.org/plot/intro.html?q=graph#%28part._.Plotting_3.D_.Graphs%29 https://docs.racket-lang.org/plot/intro.html?q=graph#%28part...

weberc2 8y ago
Disagree hard on Go vs Python. Python is my day job, but documentation is rough. You're likely not going to get documentation for all the types, and if you do it's usually in one giant page and you can't tell which class's `__str__()` docstring you're looking at. Often you'll have a method with some terse description for parameters that don't completely describe the types accepted for a parameter. Most of this stuff comes for free with godoc even if you don't take the time to add a comment, and most libraries add at least some minimal comment (the linter complains if you don't). Godoc also has really nice support for executable examples, and examples run as part of the test suite so you know they're up to date. EDIT: Racket shares many of the same problems as Python. Dynamic languages need more documentation than static languages, yet they (or rather, their users) often fail to deliver.
- jstewartmobile 8y ago
  I'm mostly comparing this: http://flask.pocoo.org/docs/1.0/api/#api http://flask.pocoo.org/docs/1.0/api/#api to this: https://golang.org/pkg/net/http/ https://golang.org/pkg/net/http/ If the source weren't hyperlinked, I'd be lost on the latter. edit: I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code.
  - weberc2 8y ago
    First of all, https://godoc.org/net/http https://godoc.org/net/http is the page to visit; it serves documentation for all public packages, not just the standard library, and it's generally a little nicer. That everything is on the same site is a big deal because maintainers don't have to link to their dependencies and readers don't have to deal with the inconsistent presentation of documentation across the ecosystem. The distinction I see is that someone put a lot more care into Flask's documentation (including the theme, which is actually a little hard to read since it renders certain things in small italic font), which is great but not indicative of the broader ecosystem. The most significant distinction wrt readability is that the Go page has types for _every_ parameter with links to the type definition. For all of the care put into the Flask doc, you still see things like this all over: > view_func – the function to call when serving a request to the provided endpoint I have no idea what the signature of that callback is. Meanwhile Go has https://godoc.org/net/http#HandleFunc https://godoc.org/net/http#HandleFunc which clearly shows the type for the handler callback (with links to types): func HandleFunc(pattern string, handler func(ResponseWriter, *Request)) > I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code. I tried to use Racket (it looks really neat), but I just spent so much time trying to figure out what to pass into each function. It was nearly impossible since types are often absent. That's just not how I want to spend my free time. :(
    - jstewartmobile 8y ago
      That sounds like a stronger defense of types than Go's documentation.
      - weberc2 8y ago
        It largely is. Formalized types allow a documentation tool to do a lot of heavy lifting. But Go's documentation system is still quite a lot nicer than javadoc, doxygen, etc. for other statically typed languages.
- masklinn 8y ago
  > Godoc also has really nice support for executable examples, and examples run as part of the test suite so you know they're up to date. Ah yes, the nice godoc feature which only got added to the python stdlib in checks note 2001.
  - weberc2 8y ago
    I didn't mean to convey that it didn't exist in Python; I was just remarking that it was a nice feature. No need for the snark.
- XorNot 8y ago
  You absolutely want to add documentation linters to your build process as early in any project as you can. Just requiring that something be in the function docstring is usually enough to get people to put at least a minimal amount of description there.
- pjmlp 8y ago
  I started using Python with version 1.6, and never used for anything more than scripting tasks, so my experience is mostly related to the official docs. The manuals provided with Python are great when compared with quite a few alternatives, some of them require to go buy a book to properly learn them.

weberc2 8y ago

Disagree hard on Go vs Python. Python is my day job, but documentation is rough. You're likely not going to get documentation for all the types, and if you do it's usually in one giant page and you can't tell which class's `__str__()` docstring you're looking at. Often you'll have a method with some terse description for parameters that don't completely describe the types accepted for a parameter. Most of this stuff comes for free with godoc even if you don't take the time to add a comment, and most libraries add at least some minimal comment (the linter complains if you don't). Godoc also has really nice support for executable examples, and examples run as part of the test suite so you know they're up to date. EDIT: Racket shares many of the same problems as Python. Dynamic languages need more documentation than static languages, yet they (or rather, their users) often fail to deliver.

jstewartmobile 8y ago
I'm mostly comparing this: http://flask.pocoo.org/docs/1.0/api/#api http://flask.pocoo.org/docs/1.0/api/#api to this: https://golang.org/pkg/net/http/ https://golang.org/pkg/net/http/ If the source weren't hyperlinked, I'd be lost on the latter. edit: I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code.
- weberc2 8y ago
  First of all, https://godoc.org/net/http https://godoc.org/net/http is the page to visit; it serves documentation for all public packages, not just the standard library, and it's generally a little nicer. That everything is on the same site is a big deal because maintainers don't have to link to their dependencies and readers don't have to deal with the inconsistent presentation of documentation across the ecosystem. The distinction I see is that someone put a lot more care into Flask's documentation (including the theme, which is actually a little hard to read since it renders certain things in small italic font), which is great but not indicative of the broader ecosystem. The most significant distinction wrt readability is that the Go page has types for _every_ parameter with links to the type definition. For all of the care put into the Flask doc, you still see things like this all over: > view_func – the function to call when serving a request to the provided endpoint I have no idea what the signature of that callback is. Meanwhile Go has https://godoc.org/net/http#HandleFunc https://godoc.org/net/http#HandleFunc which clearly shows the type for the handler callback (with links to types): func HandleFunc(pattern string, handler func(ResponseWriter, *Request)) > I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code. I tried to use Racket (it looks really neat), but I just spent so much time trying to figure out what to pass into each function. It was nearly impossible since types are often absent. That's just not how I want to spend my free time. :(
  - jstewartmobile 8y ago
    That sounds like a stronger defense of types than Go's documentation.
    - weberc2 8y ago
      It largely is. Formalized types allow a documentation tool to do a lot of heavy lifting. But Go's documentation system is still quite a lot nicer than javadoc, doxygen, etc. for other statically typed languages.
masklinn 8y ago
> Godoc also has really nice support for executable examples, and examples run as part of the test suite so you know they're up to date. Ah yes, the nice godoc feature which only got added to the python stdlib in checks note 2001.
- weberc2 8y ago
  I didn't mean to convey that it didn't exist in Python; I was just remarking that it was a nice feature. No need for the snark.
XorNot 8y ago
You absolutely want to add documentation linters to your build process as early in any project as you can. Just requiring that something be in the function docstring is usually enough to get people to put at least a minimal amount of description there.
pjmlp 8y ago
I started using Python with version 1.6, and never used for anything more than scripting tasks, so my experience is mostly related to the official docs. The manuals provided with Python are great when compared with quite a few alternatives, some of them require to go buy a book to properly learn them.