LWN: Comments on "Testable Examples in Go"

Testable Examples in Go

kloczek — Tue, 12 May 2015 11:26:08 +0000

> The much simpler approach of having regularly-compiled / regression tested examples in the same directory as the documentation is probably more my speed.

$ make all
$ make check

Testable Examples in Go

jzbiciak — Tue, 12 May 2015 04:50:26 +0000

Not to mention Donald Knuth's literate programming which goes a step further. He apparently developed that in the late 70s, with WEB debuting publicly in 1981.

I have mixed emotions about literate programming personally, in as much as you need to understand both the language you're programming and the documentation markup in parallel, along with the non-linearity it enables. By non-linearity, I mean that a literate program allows you to write your program in a different order than the original programming language requires. While that can be liberating I suppose, allowing you to express your program in the order that makes the most cognitive sense to you, as opposed to the compiler, you're still programming in a third language that's neither the language of the program's compiler nor the language of the documentation markup.

Literate programming was invented and leveraged heavily by someone much smarter than I, and at times I think it requires that level of intelligence (or at least a level above mine) to use effectively. Either that, or I haven't really given it the chance it deserves. Perhaps if someone invented a programming language which was literate from the ground up...

The much simpler approach of having regularly-compiled / regression tested examples in the same directory as the documentation is probably more my speed. As Kernighan once said, “Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?” So, if I do anything while documenting a programming environment, you'll catch me leaving liberal example programs around with text to describe and dissect them out-of-band.

Testable Examples in Go

perlwolf — Mon, 11 May 2015 16:15:58 +0000

This is an old idea.

The code examples for Kernighan and Plauger's book "Software Tools" were kept in the same directory as the text and they were compiled as run regularly as well as being included in the text of the book. That dates ack to the 70's. Go was developed by Bell Labs alumni (Rob Pike and Ken Thompson) who were well aware of the development process for that earlier book, and were surely inspired by it. In fact, the same practice probably was used when Kernighan and Ritchie wrote the original edition of "The C Programming Language", which is an even closer tie to Ken Thompson.

Testable Examples in Go

pj — Sun, 10 May 2015 22:58:36 +0000

Indeed, python has had doctests in the stdlib since 2001.

Testable Examples in Go

imgx64 — Sat, 09 May 2015 02:19:05 +0000

Probably neither. Online code playgrounds have existed for a long time. I remember Ruby had one on their website in 2008, and I'm sure others existed even before that.

But this blog post isn't about that, it's about examples in documentation that get compiled and optionally executed as part of tests. I've seen this before in Python[1], but it's great to see this feature in more languages.

[1] https://docs.python.org/3/library/doctest.html

Testable Examples in Go

lsl — Sat, 09 May 2015 01:39:58 +0000

Definitely the other way around. play.golang.org existed for years and the executable examples in documentation are nothing recent, too. The only thing new here is the blog post.

Testable Examples in Go

rgs — Fri, 08 May 2015 21:32:33 +0000

i guess that was inspired from play.rust-lang.org (or maybe the other way around).