Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Executable Examples in Go

bitfieldconsulting.com

Post reply on HN
Print view View original

31–40 of 79 posts

Re: Executable Examples in Go

#31

Post by mynameisvlad »

arp242 wrote: post #29
mynameisvlad wrote: post #21

Earlier quoted context omitted.

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 au…

> 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).

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.

Re: Executable Examples in Go

#33

Post by jerf »

Waterluvian wrote: post #18

Doesn’t Rust have something like this? Where you can write code in comments and the code is actually tested?

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.

Re: Executable Examples in Go

#34

Post by davidktr »

mejutoco wrote: post #26

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.

Adding a further example: R.

https://www.rdocumentation.org/packages/utils/versions/3.6.2...

Re: Executable Examples in Go

#35

Post by tuukkah »

multani wrote: post #30

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…

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.

Re: Executable Examples in Go

#36

Post by jerf »

arp242 wrote: post #2

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".

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.

Re: Executable Examples in Go

#37

Post by arp242 »

mynameisvlad wrote: post #31
arp242 wrote: post #29

Earlier quoted context omitted.

> 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).

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 argumen…

> 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.

Re: Executable Examples in Go

#38

Post by mynameisvlad »

arp242 wrote: post #37
mynameisvlad wrote: post #31

Earlier quoted context omitted.

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 argumen…

> 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.

[flagged]

Re: Executable Examples in Go

#39

Post by 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

Re: Executable Examples in Go

#40

Post by mattkrause »

mabbo wrote: post #11

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.

Julia (Documenter.jl), Python (doctest) and R have (doctest) them too.
Post reply on HN