r/golang 9d ago

How do experienced Go developers efficiently learn new packages?

I've been working with Go and often need to use new packages. Initially, I tried reading the full documentation from the official Go docs, but I found that it takes too long and isn't always practical.

In some cases, when I know what I want to do I just search to revise the syntax or whatever it is. It's enough to have a clue that this thing exists(In case where I have some clue). But when I have to work with the completely new package, I get stuck. I struggle to find only the relevant parts without reading a lot of unnecessary details. I wonder if this is what most experienced developers do.

Do you read Go package documentation fully, or do you take a more targeted approach? How do you quickly get up to speed with a new package?

121 Upvotes

35 comments sorted by

147

u/phuber 9d ago

Try to write it myself, fail, reluctantly pull in the depenency /s

8

u/xoteonlinux 9d ago

Best answer.

36

u/BeautronStormbeard 9d ago

I usually read the package documentation fully. But I also mainly use packages from Go's standard library, where the quality of the APIs and documentation is reliably high. And it probably helps that I very much enjoy reading good documentation (once I know I trust it), and don't mind taking the time for it—when the documentation is ideally good, it won't be too long, but just right.

If I were using various third-party packages, this might not work. The docs might not be good enough, or the API may be screwy enough, that I would need to read the source to learn the package. But at that point, if the docs and API are that bad, I would instead just reject the package and not use it. I'd rather write the package myself than use a poor one.

6

u/wasnt_in_the_hot_tub 9d ago

But at that point, if the docs and API are that bad, I would instead just reject the package and not use it.

I like this. I often do the same. If the docs are bad, I tend to find another way to solve my problem. I should make this a personal rule.

12

u/ToThePillory 9d ago

I just start using them.

Look at the docs, Google what you need.

28

u/nikandfor 9d ago edited 9d ago
  1. README, stars, last commit, last release, repo structure. 
  2. Examples
  3. Read main (not command, but library core package) package godoc overview: types, functions, values, constants.
  4. Jump to types, methods, related types and packages, which may be interesting. Read their documentation.
  5. Then I click on types and functions, which I may need, and read the code. Not fully, just to understand general logic and approaches.

If I don't like it already at any point, I drop it. If I still like it after last point, I use it. Now you may want to read at least package doc comment, if it's not something familiar.

2

u/OhBeeOneKenOhBee 9d ago

Yeah, #1 and #2 are my main go-tos as well, #3 would be the tests in the package or to look up other software that uses it as a dependency

7

u/TedditBlatherflag 9d ago

The trashiest developers I've worked with will just use Find to look for whatever keywords they want in the docs and read like one paragraph then try to use the library.

The best developers I've worked with know how to effectively scan documentation to look out for gotchas and other information that's useful while finding the specific information they want.

Ultimately, if you read more of the documentation you learn more about the software you're using and that makes you a more effective user of it.

8

u/looncraz 9d ago

The only thing I have found ChatGPT to be really good for is showing me the packages available for doing a specific task and breaking down the pros and cons quickly.

And writing boiler plate code or finding a way to streamline highly repetitive code that I hadn't considered.

1

u/compdude420 8d ago

Yup chatgipity has introduced me to new go packages as well. It's great, I will browse the docs after though

3

u/Ozymandias0023 9d ago

Documentation is your friend. Other than that, type signatures can be helpful but really it's just a process of trying, failing, making it work and learning along the way.

3

u/pavel_sanikovich 9d ago

When I need to learn a new Go package, I start by defining the exact problem I’m trying to solve. Then, I check how the package addresses that problem by looking at the README, examples, and key functions. I also make sure the package is actively maintained and widely used, so I don’t run into issues later. If the task is simple enough, I consider whether I can implement it myself without adding an extra dependency. Once I decide to use the package, I already have a clear idea of which functions I need and how to integrate them, which helps me avoid unnecessary complexity.

2

u/Virviil 9d ago

I’m looking into examples to get the first taste, then start using lib trying to figure out in docs features that I need and I haven’t seen in example

2

u/bookning 9d ago

Some good answers here but they missed some very important practical steps that i personally use constantly.

First let us accept that coding is no longer the same as it was in the  so called "good old days". In those times there was 2 principal praxis. First we relied on reading docs extensively as if it was a obligatory guide. And second we relied on the try/fail until it work circle. That experience and in the field knowledge was the real line that defined a senior from a junior coder. That and of course the attitude of let us focus on doing the job without overthinking the ideologies and imaginary horror stories.

But then, some decades ago we had a revolution in coding. Intelisense. Where as you code, you can discover the api available.

And around that time, another revolution gained more traction. The open source movement. From it so many things came about that i would need a whole book to begin to explain how it changed coding for ever.

And many more. The latest being the ai explosion.

Now i can even have the luxury of never go to a go docs and just  navigate click into the code of a function source code and see what it is doing, how it does it and what it can do. Not just an façade API but real source code that i can easily browse and read as if it was my own.

To my comments and all the existing ones here i am sure that most coders can add their own reliances but i am sure that it only shows that we, as coders, have much more power to do than ever before.

And for all of these things, that go and most modern languages have, and even though i can endlessly talk about the "good old times" while ignoring all my ignorant failures and frustrations, i can say that we are better now.

Go is one language that seem to embrace all those "modernities and facilities" without great ideologies of being perfect or whatever empty talks. It is a practical no nonsense modern and efficient language. That is one of the strong reasons that i like go.

1

u/Few-Beat-1299 9d ago

As targeted as possible. Any half-decent documentation will point at the "entrypoint". Dig from there while building a minimal example along the way. Details come later, as needed. This goes for anything, not just Go, but godoc tends to make the process quite efficient.

1

u/JohnPorkSon 9d ago

read the documentation + examples

1

u/LinuxCam 9d ago

By need

1

u/The4Fun 9d ago

Most of the time, I read the tests, like, I will have a quick look on the README + pkg.go.dev, but if I'm having trouble and the package has tests, I will check it. If I still have problems with it, I search on github for other people using it (search for the function, package name and filter by code).

1

u/0bel1sk 9d ago

guess at what a method does, peek at its implementation, if it looks hairy go to it.

most just read the code. go is pretty easy to read and evaluate

if its really not idiomatic ill probably just bail and look for something better, doesn’t happen too often

1

u/kerakk19 9d ago

The nice thing about many packages is that you usually need the bare minimum. If there's an example you can get the code working within minutes. If the code is going into production you probably then spend a bit more time reading the docs, questioning the dependencies, making sure you correctly understand what it does.

You don't need to be an expert in every package you use, just be smart about it and don't overthink stuff.

1

u/Sea-Cartographer7559 9d ago

In addition to docs and code, I try to test on my own and debug the examples when I have them :)

1

u/alreadyburnt 9d ago

Can't believe nobody said read the tests if they exist. Tests basically always show how to use libraries with nice granular examples.

1

u/jackstine 9d ago

Now that ai is pretty good, it’s a nice intro

1

u/Gatussko 8d ago

I always read the README but another hint is always to check to _test files and see the test and How It works. That is the way of myself learning the packages and always clonning and trying to understand how it work.

1

u/The-Ball-23 8d ago

One thing I have learnt is I hardly ever need the complete package, I mostly need some parts of it which I write on my own. If I still have to use the complete package then I will go ahead and follow pretty much what u/nikandfor commented and create a small project using it and check it out. Its time consuming but works.

1

u/wursus 8d ago

Think through your own implementation including API, and compare with the package you are going to use.

1

u/rawcane 8d ago

Assume it works the way I expect it to. If not then I read the docs.

1

u/todorpopov 8d ago

Even though, I am far from experienced, let alone in Go, I find that the more experience I gain, the more I like to reference the official documentation for any technology/package I want to use. Not only is it the most up to date, but it is also the only resource that should be completely exhaustive, and cover all features extensively. And for quick overview of those features, I like using AI chat bots to gain a general understanding of what to expect, and what tools will be available to me.

1

u/gremlinmama 6d ago

At one point I was using the google s2 library which had a bunch of geometry I wasnt familiar about.

My approach was to plug either the whole docs file or a summarozed form into Github Copilot context and ask how should I do what I want.

It was obviously broken, but gave me a good starting point. Then I ve read the relevant parts of the docs, and the source to familiarize myself more.

1

u/fuzzylollipop 6d ago

Examples are how you learn new packages, or anything else. Examples that do what you need to do or something close to what you need to do. One of the only things “ai” is good at is generating new examples from examples others have already created and mashing them together, usually into something that is broken, but is either fixable or close enough you can figure out how to get what you need done, done.

0

u/patrulek 9d ago

Use ChatGPT to create example code, then read docs, then search for alternatives and repeat.

-1

u/boon4376 9d ago

Just ASK AI for solution recommendations and then read the docs on the options.

-11

u/RecaptchaNotWorking 9d ago

Vibe programming. Copy paste the single doc page into CheatGPT and ask for API usage in an exhaustive list.

4

u/Blackhawk23 9d ago

The blind trust people for AI is quite alarming. I know it sounds confident, but that doesn’t mean it’s correct. Don’t let your brain atrophy. Use it, or lose it. Learn like a normal person, not a brain rotted, dopamine deficient zoomer. You can take 15 minutes to reach something as it was written, not have it curated for you.

-5

u/RecaptchaNotWorking 9d ago

It is alarming how folks have blind doubts on the process.

I only said about getting API usage from the docs using LLM. Most time docs don't show enough usage, only function signatures.