Testable Examples in Go
At the Go Blog, Andrew Gerrand provides a look at the language's
approach to combining example code and documentation. "Godoc examples
are snippets of Go code that are displayed as package documentation
and that are verified by running them as tests. They can also be run
by a user visiting the godoc web page for the package and clicking the
associated "Run" button. Having executable documentation for a package
guarantees that the information will not go out of date as the API
changes.
" Each package's examples are compiled as part of the
package test suite; examples can also (optionally) be executed in
order to capture failures with the testing framework.
Posted May 8, 2015 21:32 UTC (Fri)
by rgs (guest, #73061)
[Link] (3 responses)
Posted May 9, 2015 1:39 UTC (Sat)
by lsl (subscriber, #86508)
[Link]
Posted May 9, 2015 2:19 UTC (Sat)
by imgx64 (guest, #78590)
[Link] (1 responses)
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.
Posted May 10, 2015 22:58 UTC (Sun)
by pj (subscriber, #4506)
[Link]
Posted May 11, 2015 16:15 UTC (Mon)
by perlwolf (guest, #46060)
[Link] (2 responses)
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.
Posted May 12, 2015 4:50 UTC (Tue)
by jzbiciak (guest, #5246)
[Link] (1 responses)
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.
Posted May 12, 2015 11:26 UTC (Tue)
by kloczek (guest, #6391)
[Link]
$ make all
??
Testable Examples in Go
Testable Examples in Go
Testable Examples in Go
Testable Examples in Go
Testable Examples in Go
Testable Examples in Go
Testable Examples in Go
$ make check