Executable Examples in Go
Comments
multani
roflchoppa
Dude doc tests are the one thing I really really miss when I moved over from working on python backend to a typescript backend…
Actually unittest as a whole, testing in ts/JS feels like a mess, everything is just fanned out everywhere, there has been such a lack of structure in our codebase. I’m sure there are examples of well organized testing suites, but I’ve yet to find them.
capableweb
Thing is, most testing frameworks/libraries in JS gives you a lot of freedom to structure the overall testing architecture however you want, without being much picky about it. That means teams writing the tests have to carefully consider their testing architecture, treating it like production code. But most people don't consider testing code "production" code, they treat it like something they should be able to write once and then kind of forget about it.
So zero regard for architecture will lead to "everything is just fanned out everywhere" and "lack of structure", no matter what language you're using, not just JS. What you're talking about tells us more about your team's engineering practices than how messy the JS testing ecosystem is.
roflchoppa
I agree 100% with the statement that it tells us more about our engineering team practices, but the question I have is, how to get it better? Python provides rich built ins, which make it easy to compose a rich suite.
It appears that no one else has an issue with it in my group, but I’m the oddball, these guys come from a TS/JS background. They don’t appear to express concern with it.
Are there resources that you can recommend that I can use to get better?
winrid
I was blown away this year when I realized Django REST Framework was reading comments from classes to generate docs, for example the welcome message on this page [0] comes from a comment in the code.
I've come to really love Python, in all its somewhat slow glory.
bradbeattie
Since 2001, it seems: https://github.com/python/cpython/blob/3.11/Lib/doctest.py#L...
tuukkah
I don't know why you'd need to run an example apart from when running tests. After all, the examples have been tested to output what the example says.
multani
That can be useful because the doc website turns into some kind of sandbox where you can tweak directly the test function and see the result without having to write the code yourself.
szopa
Ok, this is indeed a very well kept secret. I have been programming go for a really long time, and was even a readability reviewer at Google, and I had no idea. Thank you, OP.
mabbo
Elixir has a similar concept with doc tests:
https://elixir-lang.org/getting-started/mix-otp/docs-tests-a...
You're comments/docs for the method can have demonstration code that is executed when you run your tests, ensuring your docs remain accurate.
It's a great pattern.
mattkrause
Julia (Documenter.jl), Python (doctest) and R have (doctest) them too.
otherme123
Nim: runnableExamples.
xrd
I came here to say this and you beat me to it! Love this part of elixir. It's a good way to think about your functions: if you can't write a doc test, you've probably written a function with side effects.
nazka
Is it similar to what Rust does?
ilyt
I wondered why the hell people find that as a surprise here and figured out that is because the syntax for examples is not documented in [1] how to write a documentation part but instead in [2] "how our testing framework works"
Waterluvian
Doesn’t Rust have something like this? Where you can write code in comments and the code is actually tested?
jerf
Go's contribution here is not so much inventing the idea... Python's had it since the 20th century, for instance... but accidentally hiding them in the docs so that so many people, even long-time Go programmers, don't realize Go has it too.
andrewjf
Yes, they’re called documentation tests.
https://doc.rust-lang.org/rustdoc/write-documentation/docume...
the_gipsy
Lightyears ahead.
nrub
Yup
peter_l_downs
If it's a secret, it's only because the godoc format is so strangely obtuse about some things. It's sort of like markdown, but sort of not. You can do lists, kind of. You can do links, kind of. What a pain!
WalterBright
D's had that for many years. It's not a secret!
https://dlang.org/phobos/std_algorithm_searching.html#.any
See the buttons below the example code. You can even edit the examples and try variations.
jchw
I was curious for exactly how long "many years" was, and it appears it was added sometime between 2016 to 2017. The last archive without it is from 2016, the next archive with it is 2017:
https://web.archive.org/web/20160405080736/https://dlang.org...
Now that's of course just the website feature. Maybe D had executable examples that were tested by the compiler before Go, which would still be very interesting. However, it does appear Go at least did have the in-browser feature as far back as 2015:
Not that this matters for much other than historical interest: good ideas like this should be copied shamelessly (and obviously it's not a terribly original idea to begin with, just a good implementation of it.)
WalterBright
> Maybe D had executable examples that were tested by the compiler before Go
Sounds like D's ability to specify unit tests in production source code, and have them optionally executed, fits the bill for that.
https://dlang.org/spec/unittest.html
Builtin unit tests were a great leap forward for code verification.
jchw
Having unit testing built-in to the programming language and tooling is a huge plus, absolutely. I don't know who originally came up with this, but I swear, it would be worth some recognition :) (And thankfully, whoever did originally come up with this idea, it has been copied a ton by the recent crop of programming language designs.)
abecedarius
The E language supported doctests when I came to it in the 90s: http://erights.org/elang/tools/updoc.html
It's the earliest I'm aware of.
WalterBright
Quite a few D features have made it into other languages:
1. integrated documentation
2. unit tests
3. 1_000_000 literals
4. ranges
5. compile time function execution
6. static if
pjmlp
Unless there is a time machine to have D come up before Smalltalk and Common Lisp/Interlisp-D, it definitely did not do 1, 2 and 3 as influence to other languages.
WalterBright
Those languages have indeed been around decades before D. But somehow those features did not move into the general language community until after D was very successful with them and popularized those features in a modern language.
BTW, the 1_000_000 specifically came from Ada 1983.
pjmlp
The agile movement is what popularised them, driven by key figures in the Smalltalk and Lisp community, pushing them via Java, Ruby and Python.
All of them predating D.
guraf
The secret is D's existence.
jamietanna
Note that without the `Output:` line you can silently not be running these tests - https://github.com/golangci/golangci-lint/issues/3084 covers when this can be problematic and there's now a golangci-lint integrated linter for catching it
o1y32
I don't understand why this is an article and why this shows up on hacker news at all. Other languages have been doing this for a long time as well. And there is no "secret" "kept" by anyone.
davelondon
Check out my https://github.com/dave/rebecca package for a neat way of building readme docs by embedding Go docs and examples.
It generates the big readme for https://github.com/dave/jennifer (see https://github.com/dave/jennifer/blob/master/README.md.tpl).
badrequest
Dave I've been a heavy user of Jennifer for quite some time, thank you for making such an awesome library.
mejutoco
Adding to the list of languages that also have this: python. Unfortunately searching on google "python executable comments" only returns lobotomized results about what comments in python are.
detaro
"doctests" is the name used in the python world
davidktr
Adding a further example: R.
https://www.rdocumentation.org/packages/utils/versions/3.6.2...
starttoaster
Neat! I’ve seen these in many high profile package’s GoDocs but never knew how to make them myself.
awinter-py
> We’ve probably all had the unpleasant experience of copying and pasting an example code snippet from someone’s documentation, and finding not only that it doesn’t behave the way we expected, but that it doesn’t even compile. Not a good look for the project.
middle ground here is linting the examples if you can't make them interactive, but yes this is powerful
forever shocked by huge oss packages with seemingly lots of contributors and stars where the docs are simply wrong
corollary: if your framework cannot compile a working program from a single small file (looking at you xcode), this kind of 'here's a working example' documentation becomes much harder
lloydatkinson
Pretty common for languages and frameworks to have this. Why is this being advertised as go only?
jolux
Rust and Elixir do this too.
otikik
I am 75% sure Rust has a similar thing
jghn
R has had this since at least 2000. The man pages for each function contain an "examples" block, and these are expected (but don't need) to be executable.
They then took it a step further a couple of years later going down the literate programming path with SWeave, and later Rmd.
Pbhaskal
The book "the go programming language" has explained it too.
Patrickmi
tbh am not really really surprised but the fact that using Go and this not coming in mind is really surprising
jpoz
Great write up
arp242
It's not a secret; they're all over the place.
The article title is "Executable examples in Go". You shouldn't editorialize titles, especially when it makes the title significantly worse.
Edit: seems the article title has changed or is A/B tested so never mind I guess (can't delete since there are replies), but it's still not a "secret".
jerf
It certainly isn't a secret in the sense that they didn't want you to know about this feature, but it is a de facto secret in that you can find people who have been programming in Go for year who don't realize they exist. In addition to the other replies you can already find in this HN discussion mentioning that, I can attest to the fact that I've personally introduced them to multi-year programmers in Go as well.
I hypothesize that a very simple and easy-to-make mistake created this situation, and it is as simple as this: Godoc collapses the examples. Behind undistinguished links. Look at the current rendering for the documentation for net/http, the core HTTP package: https://pkg.go.dev/net/http Your challenge is to scroll through the package with the scrollbar, looking for the Examples.
Of course, if enough people try this, some will find them quickly. Someone will simply jerk their mouse and scroll right to it in a quarter of a second, of course. But in general, they're not easy to find, even when I'm telling you to look for them. If you don't even know they are there they are super easy to miss. The main listing for the examples is between the Index and the Constants. In the left section breakdown, they don't get their own top-level section but are instead by default buried unexpanded below Index, where I would personally assert they don't belong. Even if you scroll to the documentation for a specific function that includes an example, such as Hijacker: https://pkg.go.dev/net/http#Hijacker , I think it's very easy to be scanning through and miss the little Example link in all the noise. And again, in this context I'm calling your attention to it; in normal circumstances I think link blindness kicks in and people can read these docs for years without catching them.
And then of course even if you do catch them it's easy to come away thinking it must be something special the standard library can do but you can't, because that is a Go thing, and so few 3rd party packages avail themselves of this. But you can easily do them yourself. It's little more than a slightly specially-formatted test function.
meling
You make some good points about the examples visibility in the docs. I suggest that you write up an issue on Go’s issue tracker.
arp242
Well, it doesn't really matter – my main complaint was that the title was editorialized in a way that I personally wouldn't appreciate for my own article, but now the article title changed and the submitter may be the article author (not entirely clear). I would have deleted my previous post if I could.
mynameisvlad
Are we looking at the same article? Its title quite clearly is “Go’s best-kept secret: executable examples” so the title here is only minorly editorialized.
jchw
It seems as though the submitter is also the article author and changed it on the page to match the HN title.
https://web.archive.org/web/20230117212610/https://bitfieldc...
This is an interesting conundrum. Clearly the new title was chosen because it sounds more alluring; I mean, it hit the front page. But also, the OP could've easily done this prior to submitting and it would be totally normal, since people adjust article and post titles all the time.
Does come off as mildly sneaky when you do it in this order, but maybe I'm just nitpicky.
HerrFolgreich
In arp242's defense, I opened the article a couple of minutes ago and it showed the same title he was faced with until I refreshed the page.
arp242
It shows like that for me too now, but I am 100% sure this wasn't the case a few minutes ago. I copy/pasted the title.
mynameisvlad
[dead]
Jtsummers
The article (at the linked page, not here) title was changed. The original was as GP described it, and in the last few minutes it was altered to match the HN title.
jrockway
I also like how the HN submitter changed the name of the programming language to "Golang". I guess they also call Ruby "ruby-lang" since they didn't get "ruby.org"?
mynameisvlad
Golang is a common way to refer to Go, especially for SEO purposes. “Go” is hard to search for.
https://go.dev/doc/faq#go_or_golang
I use “golang” for clarity all the time, and I’m sure many others do as well. There’s no ambiguity you’re talking about the language then.
arp242
I personally strongly prefer to use Go, and would never use "golang" or "Golang", but I don't mind if other people do and I'd never complain about it. The reason for this is simply that I don't like the sound of the word "golang"; there are some other words I avoid for similar reasons, I think everyone has a few of those.
The thing is that the article title uses Go while the submission here uses Golang. I wouldn't be too happy if someone submitted one of my articles and changed words like that, especially if it's to something I dislike. That's also why I complained about the editorializing in the first place, because I'd be a bit peeved if someone added something like "best-kept secret" in there (but the article title changed, so that's now a moot point).
Conversely, I'd also never change "golang" to "Go" when submitting something.
mynameisvlad
Based on the submitter’s posting history and change in original article title, I’m going to go on a limb and say that the submitter is the original author.
Yeah, the names don’t match, but out of all of the things they submitted, at least half are articles from this site.
But beyond that, I mean, does it matter? You might not appreciate it, sure, but you’re also not the original author. I’d get the argument if the author came in and said it, but at this point this just seems like complaining for complaining’s sake and you not agreeing with the phrasing used in the article or submission title. That’s certainly your opinion to have, but is there any benefit to expressing it? This doesn’t seem like a relevant discussion about the article contents.
arp242
> I mean, does it matter? You might not appreciate it, sure, but you’re also not the original author.
Well, no, but I'd rather not assume anything: just let the author pick the title.
(I assumed that "gus_leonel" wasn't the author, since John Arundel has his own HN account under his regular "bitfield" username, but they do post a lot from bitfieldconsulting, so idk).
mynameisvlad
If the original author has a problem with it, they are free to come in and make the complaint themselves. It’s your opinion to have but not your argument to make and while you may not appreciate it, even if the author isn’t the submitter (I still very much think they are), they clearly did considering the article title was changed to more closely match the submission, and they have a keyboard and can make the argument for themselves if they are irked by the changes.
All this discussion seems to be doing is derailing the comment threads. Almost half the comments here are not about the article itself but your opinions on the words used in the title.
This is also a funny way to not assume anything:
> (I assumed that “gus_leonel” wasn’t the author
> Well no, but I’d rather not assume anything
I don’t see the benefit of this discussion existing in the first place, let alone continuing it, so I’m going to stop here.
arp242
> If the original author has a problem with it, they are free to come in and make the complaint themselves.
Most won't know it's posted, or won't see until after it no longer matters. "Don't editorialize" is the simplest and surest way to respect the original author.
"Don't editorialize titles unless the original title is very nondescript or clickbait-y" is not a controversial HN policy.
mynameisvlad
[flagged]
arp242
My apologies. You were already on my blocklist of toxic HN users never worth engaging with, but it seems my extension wasn't side-loaded in Firefox after a reboot so I accidentally saw your replies. Won't happen again.
dang
Whoa, please don't get personal and please don't perpetuate tit-for-tat spats on HN. I know they can be hard to extricate oneself from, but they're very much against the intended spirit here.
mynameisvlad
I guess this is what happens when you have nothing to actually rebut.
Falling back on ad hominems and irrelevant information that, frankly, nobody would ever care to know. Sometimes, you don’t have to say what’s on your mind. I would have hoped the rest of this thread would have shown you that, but clearly that didn’t happen.
Great use of all our time. At least you won’t see this comment to continue your insults of me. Something that, considering you seem to know the guidelines well, is frowned upon here.
dang
Whoa, please don't get personal and please don't perpetuate tit-for-tat spats on HN. I know they can be hard to extricate oneself from, but they're very much against the intended spirit here.
Jtsummers
> I wouldn't be too happy if someone submitted one of my articles and changed words like that
gus_leonel appears to be a pseudonym for the author of the post. They have essentially no comments and most of their submissions are related to this Bitfield Consulting. So it's the author editorializing their own submission titles.
Waterluvian
I use Golang because Go is horrible to search for.
I also get into a habit of “Rust lang” because of the video game.
Yes, I could do a bunch of search engine customization stuff or pick someone else’s favourite engine. But this is simpler.
tekla
Your preferences/likes/dislikes are irrelevant. "Golang" is a official way to refer to the Go language.
arp242
I explicitly said that it's fine to use golang. I am saying I don't like people changing my words, which is entirely reasonable and a very different argument than "never use golang".
Python also has doctest https://docs.python.org/3/library/doctest.html since ... a long time now.
The documentation tools are not as advanced as Go's and as far as I know, there's no way to "run the examples" yourself.
It's a great way to write tests for some functions though, to me the sweet spot is for small, without side effects functions. It's totally possible for bigger functions but then all the initialization code and assertions can easily get in the way and make the documentation not super clear.