Python also has doctest <a href="https://docs.python.org/3/library/doctest.html" rel="nofollow">https://docs.python.org/3/library/doctest.html</a> since ... a long time now.<p>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.<p>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.
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.
Elixir has a similar concept with doc tests:<p><a href="https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html" rel="nofollow">https://elixir-lang.org/getting-started/mix-otp/docs-tests-a...</a><p>You're comments/docs for the method can have demonstration code that is executed when you run your tests, ensuring your docs remain accurate.<p>It's a great pattern.
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"<p>- [1] <a href="https://go.dev/blog/godoc" rel="nofollow">https://go.dev/blog/godoc</a><p>- [2] <a href="https://pkg.go.dev/testing#hdr-Examples" rel="nofollow">https://pkg.go.dev/testing#hdr-Examples</a>
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!
D's had that for many years. It's not a secret!<p><a href="https://dlang.org/phobos/std_algorithm_searching.html#.any" rel="nofollow">https://dlang.org/phobos/std_algorithm_searching.html#.any</a><p>See the buttons below the example code. You can even edit the examples and try variations.
Note that without the `Output:` line you can silently not be running these tests - <a href="https://github.com/golangci/golangci-lint/issues/3084">https://github.com/golangci/golangci-lint/issues/3084</a> covers when this can be problematic and there's now a golangci-lint integrated linter for catching it
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.
Check out my <a href="https://github.com/dave/rebecca">https://github.com/dave/rebecca</a> package for a neat way of building readme docs by embedding Go docs and examples.<p>It generates the big readme for <a href="https://github.com/dave/jennifer">https://github.com/dave/jennifer</a> (see <a href="https://github.com/dave/jennifer/blob/master/README.md.tpl">https://github.com/dave/jennifer/blob/master/README.md.tpl</a>).
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.
> 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.<p>middle ground here is linting the examples if you can't make them interactive, but yes this is powerful<p>forever shocked by huge oss packages with seemingly lots of contributors and stars where the docs are simply wrong<p>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
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.<p>They then took it a step further a couple of years later going down the literate programming path with SWeave, and later Rmd.
It's not a secret; they're all over the place.<p>The article title is "Executable examples in Go". You shouldn't editorialize titles, especially when it makes the title significantly worse.<p><i>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".</i>