Executable Examples in Go
bitfieldconsulting.com
bitfieldconsulting.com
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.
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.
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.
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?
I've come to really love Python, in all its somewhat slow glory.
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.
https://doc.rust-lang.org/rustdoc/write-documentation/docume...
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.
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.)
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.
It's the earliest I'm aware of.
1. integrated documentation
2. unit tests
3. 1_000_000 literals
4. ranges
5. compile time function execution
6. static if
BTW, the 1_000_000 specifically came from Ada 1983.
All of them predating D.
It generates the big readme for https://github.com/dave/jennifer (see https://github.com/dave/jennifer/blob/master/README.md.tpl).
https://www.rdocumentation.org/packages/utils/versions/3.6.2...
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
They then took it a step further a couple of years later going down the literate programming path with SWeave, and later Rmd.
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".
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.