4 ms·

I've gotten used to golang, though it's still not my favourite language to program in by any stretch. One issue I've been having, though, is the documentation.

I've gotten used to golang, though it's still not my favourite language to program in by any stretch. One issue I've been having, though, is the documentation. Documentation for third-party modules in Python is fantastic, almost universally so. In nearly every case of using a third-party library, large or small, there's sufficient documentation to get up and running. Golang libraries, however, seem to be the opposite. In most cases there's either no documentation whatsoever on how to use things, or, more commonly, there is example code in the readme which is out of date and does not work at all. The IDE integration with golang is great, and it makes some of this a bit easier, but I also still get a ton of situations where my editor will offer some field or function that looks like what I want (and is what I'm typing to see if it will autocomplete) but once I select it it complains that there's no such field or function. Still haven't figured that out. So yeah, I dunno. The language is 'great'; it certainly has some extreme strengths and conveniences, like the fact that 'run this function with these arguments in a separate thread' is a language keyword and not some deep dive into subprocess or threading or concurrent.futures; the fact that synchronization functionality is trivially easy to access; Sync.Once feels so extremely obvious for a language where concurrency is king, and so on. Still, the ecosystem is... a bit of a mess, at the best of times. Good modules are great, all other modules are awful.

leoqa 1y ago
I quite frankly will just read the code. Go generally discourages abstractions so any code you jump into is fairly straightforward (compared to a hierarchy of abstract classes, dependency injected implementations, nested pattern matching with destructuring etc etc). Regarding your IDE issues- I’ve found the new wave of copilot/cursor behavior to be the culprit. Sometimes I just disable it and use the agent if I want it to do something. But it’ll completely fail to suggest an auto complete for a method that absolutely exists.
- treyd 1y ago
  > Go generally discourages abstractions so any code you jump into is fairly straightforward This is a really anti-intellectual take. All of software engineering is about building abstractions. Not having abstractions makes the structure less easy to understand because they're made implicit, and forces developers to repeat themselves and use brittle hacks. It's not a way to build robust or maintainable software.
  - bjt 1y ago
    Go does have plenty of abstractions. I think the more charitable interpretation is "Go generally discourages metaprogramming." Which I would agree with, and I think positively distinguishes it from most popular languages.
    - eru 1y ago
      Go mostly only have abstractions that the language designers put into the language. It is (mostly) hostile to users defining their own new abstractions. A case in point is that arrays and maps (and the 'make' function etc) were always generic, but as a user until fairly recently you couldn't define your own generic data structures and algorithms.
  - Mawr 1y ago
    Did you cherry pick that part of the sentence and ignored "(compared to a hierarchy of abstract classes, dependency injected implementations, nested pattern matching with destructuring etc etc)." on purpose or?
    - treyd 1y ago
      Yeah this is exactly the stuff that you'll have to reinvent yourself on an ad-hoc basis in any sufficiently large project. I would argue it's sorta related to Greenspun's tenth rule: https://en.m.wikipedia.org/wiki/Greenspun%27s_tenth_rule https://en.m.wikipedia.org/wiki/Greenspun%27s_tenth_rule Of course, you'll probably retreat and say "Go is better for small projects", but every large project started as a small one, and it's really hard to justify rewriting a project in a new language in a business context.
      - samdoesnothing 1y ago
        You don't need a hierarchy of abstract classes, dependency injected implementations, nested pattern matching with destructuring, etc for any project. If one decides to implement these techniques in an ad-hoc basis in Go to solve problems, that's more to do with trying to apply principles and techniques from other languages in Go.
- osigurdson 1y ago
  >> Go generally discourages... Really, there is nothing in the language that prevents you from creating crazy AbstractFactoryFactories or doing DI. What really prevents this is the community. In enterprise C# / Java, insanity is essentially mandated.
mayama 1y ago
Generally I found updated example in one of the test files. Or I could understand how to use library by reading test files in the repo. For me it's the opposite problem, python documentation is too long in some cases and it's not intuitive to find what I want if it's not trivial, and had to use websearch or llm.
- wizhi 1y ago
  Python package documentation is abysmal. It tends to read like a novel and yet still only covers surface layer details with simplistic examples. It's next to impossible to just "get an overview" of what's available: just show me the modules, classes, functions, etc. Don't make me spend 30 minutes trying to find an explanation for that one function which just takes a kwargs, which ends up only being covered in thr footnote of some random page in the documentation on something otherwise completely unrelated. It's madness.
cmckn 1y ago
I wrote a lot of Java in a past life, and the documentation situation is night and day, for sure. I think it's partly a syntax/tooling issue, and partly a cultural thing. Luckily Go's standard library (+ `/x/` modules) lets me avoid third-party dependencies in many cases. The documentation from the Go team is very good in my opinion.
antibios 1y ago
This is so true and unfortunate because golang has an inbuilt example function that closely follows the test functions. It means that all that really needs to change is how godoc promotes or badges libraries with examples.
marcus_holmes 1y ago
I think Go de-emphasises the ecosystem a lot. Generally gophers just use the standard library as much as possible. There isn't the usual set of "must-have" dependencies, and generally speaking when a gopher tries to solve a problem, the first step isn't to search for a 3rd party library that solves it for them. Obviously this is a broad generalisation and there are plenty of gophers who swear by using one or more libraries, and there are plenty of gophers who do rely on third-paarty dependencies. But this is still noticeably less prevalent than in many other languages, especially the more popular ones in web dev. As others have said, it also helps that Go code is easy to read and emphasises simplicity. The code is often more readable than the documentation, for sure. Whether you consider this bad documentation is up to you ;)
Grokify 1y ago
I enjoy the Go ecosystem quite a bit and haven't found many issues with documentation. I love how open source modules are documented on pkg.go.dev, including those from major providers, like AWS, Google, etc. Every library has the same references. When examples are useful, such as with charting modules, I've found that the projects do provide them. On the occasion where the README.md code is out of date, it's been easy for me to check pkg.go.dev and update it myself.
akkad33 1y ago
> my editor will offer some field or function that looks like what I want (and is what I'm typing to see if it will autocomplete) but once I select it it complains that there's no such field or function Are you using copilot?

leoqa 1y ago

I quite frankly will just read the code. Go generally discourages abstractions so any code you jump into is fairly straightforward (compared to a hierarchy of abstract classes, dependency injected implementations, nested pattern matching with destructuring etc etc). Regarding your IDE issues- I’ve found the new wave of copilot/cursor behavior to be the culprit. Sometimes I just disable it and use the agent if I want it to do something. But it’ll completely fail to suggest an auto complete for a method that absolutely exists.

treyd 1y ago
> Go generally discourages abstractions so any code you jump into is fairly straightforward This is a really anti-intellectual take. All of software engineering is about building abstractions. Not having abstractions makes the structure less easy to understand because they're made implicit, and forces developers to repeat themselves and use brittle hacks. It's not a way to build robust or maintainable software.
- bjt 1y ago
  Go does have plenty of abstractions. I think the more charitable interpretation is "Go generally discourages metaprogramming." Which I would agree with, and I think positively distinguishes it from most popular languages.
  - eru 1y ago
    Go mostly only have abstractions that the language designers put into the language. It is (mostly) hostile to users defining their own new abstractions. A case in point is that arrays and maps (and the 'make' function etc) were always generic, but as a user until fairly recently you couldn't define your own generic data structures and algorithms.
- Mawr 1y ago
  Did you cherry pick that part of the sentence and ignored "(compared to a hierarchy of abstract classes, dependency injected implementations, nested pattern matching with destructuring etc etc)." on purpose or?
  - treyd 1y ago
    Yeah this is exactly the stuff that you'll have to reinvent yourself on an ad-hoc basis in any sufficiently large project. I would argue it's sorta related to Greenspun's tenth rule: https://en.m.wikipedia.org/wiki/Greenspun%27s_tenth_rule https://en.m.wikipedia.org/wiki/Greenspun%27s_tenth_rule Of course, you'll probably retreat and say "Go is better for small projects", but every large project started as a small one, and it's really hard to justify rewriting a project in a new language in a business context.
    - samdoesnothing 1y ago
      You don't need a hierarchy of abstract classes, dependency injected implementations, nested pattern matching with destructuring, etc for any project. If one decides to implement these techniques in an ad-hoc basis in Go to solve problems, that's more to do with trying to apply principles and techniques from other languages in Go.
osigurdson 1y ago
>> Go generally discourages... Really, there is nothing in the language that prevents you from creating crazy AbstractFactoryFactories or doing DI. What really prevents this is the community. In enterprise C# / Java, insanity is essentially mandated.

mayama 1y ago

Generally I found updated example in one of the test files. Or I could understand how to use library by reading test files in the repo. For me it's the opposite problem, python documentation is too long in some cases and it's not intuitive to find what I want if it's not trivial, and had to use websearch or llm.

wizhi 1y ago
Python package documentation is abysmal. It tends to read like a novel and yet still only covers surface layer details with simplistic examples. It's next to impossible to just "get an overview" of what's available: just show me the modules, classes, functions, etc. Don't make me spend 30 minutes trying to find an explanation for that one function which just takes a kwargs, which ends up only being covered in thr footnote of some random page in the documentation on something otherwise completely unrelated. It's madness.

cmckn 1y ago

I wrote a lot of Java in a past life, and the documentation situation is night and day, for sure. I think it's partly a syntax/tooling issue, and partly a cultural thing. Luckily Go's standard library (+ `/x/` modules) lets me avoid third-party dependencies in many cases. The documentation from the Go team is very good in my opinion.

antibios 1y ago

This is so true and unfortunate because golang has an inbuilt example function that closely follows the test functions. It means that all that really needs to change is how godoc promotes or badges libraries with examples.

marcus_holmes 1y ago

I think Go de-emphasises the ecosystem a lot. Generally gophers just use the standard library as much as possible. There isn't the usual set of "must-have" dependencies, and generally speaking when a gopher tries to solve a problem, the first step isn't to search for a 3rd party library that solves it for them. Obviously this is a broad generalisation and there are plenty of gophers who swear by using one or more libraries, and there are plenty of gophers who do rely on third-paarty dependencies. But this is still noticeably less prevalent than in many other languages, especially the more popular ones in web dev. As others have said, it also helps that Go code is easy to read and emphasises simplicity. The code is often more readable than the documentation, for sure. Whether you consider this bad documentation is up to you ;)

Grokify 1y ago

I enjoy the Go ecosystem quite a bit and haven't found many issues with documentation. I love how open source modules are documented on pkg.go.dev, including those from major providers, like AWS, Google, etc. Every library has the same references. When examples are useful, such as with charting modules, I've found that the projects do provide them. On the occasion where the README.md code is out of date, it's been easy for me to check pkg.go.dev and update it myself.

akkad33 1y ago

> my editor will offer some field or function that looks like what I want (and is what I'm typing to see if it will autocomplete) but once I select it it complains that there's no such field or function Are you using copilot?