[HN Gopher] Executable Examples in Go
___________________________________________________________________
Executable Examples in Go
Author : gus_leonel
Score : 203 points
Date : 2023-06-10 14:37 UTC (8 hours ago)
(HTM) web link (bitfieldconsulting.com)
(TXT) w3m dump (bitfieldconsulting.com)
| o1y32 wrote:
| 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.
| [deleted]
| WalterBright wrote:
| 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.
| guraf wrote:
| The secret is D's existence.
| [deleted]
| jchw wrote:
| 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:
|
| https://go.dev/blog/examples
|
| 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 wrote:
| > 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 wrote:
| 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.)
| WalterBright wrote:
| 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
| abecedarius wrote:
| 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.
| lloydatkinson wrote:
| Pretty common for languages and frameworks to have this. Why is
| this being advertised as go only?
| Patrickmi wrote:
| tbh am not really really surprised but the fact that using Go and
| this not coming in mind is really surprising
| mabbo wrote:
| 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.
| nazka wrote:
| Is it similar to what Rust does?
| xrd wrote:
| 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.
| mattkrause wrote:
| Julia (Documenter.jl), Python (doctest) and R have (doctest)
| them too.
| otherme123 wrote:
| Nim: runnableExamples.
| mejutoco wrote:
| 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 wrote:
| "doctests" is the name used in the python world
| davidktr wrote:
| Adding a further example: R.
|
| https://www.rdocumentation.org/packages/utils/versions/3.6.2...
| jamietanna wrote:
| 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
| davelondon wrote:
| 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 wrote:
| Dave I've been a heavy user of Jennifer for quite some time,
| thank you for making such an awesome library.
| szopa wrote:
| 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.
| multani wrote:
| 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.
| tuukkah wrote:
| 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 wrote:
| 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.
| winrid wrote:
| 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.
|
| [0] https://govscent.org/api/
|
| I've come to really love Python, in all its somewhat slow
| glory.
| roflchoppa wrote:
| 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 wrote:
| 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.
| bradbeattie wrote:
| Since 2001, it seems:
| https://github.com/python/cpython/blob/3.11/Lib/doctest.py#L...
| otikik wrote:
| I am 75% sure Rust has a similar thing
| peter_l_downs wrote:
| 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!
| jghn wrote:
| 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.
| ilyt wrote:
| 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"
|
| - [1] https://go.dev/blog/godoc
|
| - [2] https://pkg.go.dev/testing#hdr-Examples
| Waterluvian wrote:
| Doesn't Rust have something like this? Where you can write code
| in comments and the code is actually tested?
| the_gipsy wrote:
| Lightyears ahead.
| jerf wrote:
| 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.
| nrub wrote:
| Yup
| andrewjf wrote:
| Yes, they're called documentation tests.
|
| https://doc.rust-lang.org/rustdoc/write-documentation/docume...
| arp242 wrote:
| 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"._
| mperham wrote:
| https://xkcd.com/1053/
| jerf wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| jrockway wrote:
| 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 wrote:
| 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 wrote:
| 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.
| Jtsummers wrote:
| > 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 wrote:
| 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.
| mynameisvlad wrote:
| 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 wrote:
| > 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 wrote:
| 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 wrote:
| > 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 wrote:
| [flagged]
| arp242 wrote:
| 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.
| [deleted]
| mynameisvlad wrote:
| 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 wrote:
| 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.
|
| https://news.ycombinator.com/newsguidelines.html
| dang wrote:
| 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.
|
| https://news.ycombinator.com/newsguidelines.html
| tekla wrote:
| Your preferences/likes/dislikes are irrelevant. "Golang"
| is a official way to refer to the Go language.
| arp242 wrote:
| 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".
| Jtsummers wrote:
| 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.
| arp242 wrote:
| 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 wrote:
| [dead]
| HerrFolgreich wrote:
| 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.
| [deleted]
| jchw wrote:
| 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.
| starttoaster wrote:
| Neat! I've seen these in many high profile package's GoDocs but
| never knew how to make them myself.
| jolux wrote:
| Rust and Elixir do this too.
| jpoz wrote:
| Great write up
| awinter-py wrote:
| > 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
___________________________________________________________________
(page generated 2023-06-10 23:01 UTC)