The package documentation, blog and present abilities of the go ecosystem are already great, but as a former user of knuth’s cweb I experienced the power of the real literate approach, when writing algorithms.
“The main idea is to regard a program as a communication to human beings rather than as a set of instructions to a computer.” (found as a Knuth quote on Literate programming - HaskellWiki)
There are several discussions about this topic that quickly lead into the idea, that having a way to generate web content from comments in the code, would make a program literate. But having some package documentation in the code compares to a literate program, as a pile of notes compares to a leather coated book, containing a collection of elaborated novels.
One of the main powers of literate programming is to focus on the main algorithms, while hiding the more technical sections of the code, from the human reader.
Literate programs split the code into sections that might not have to do anything with the text structure of the code for the go compiler. A literate programming tool basically has to restructure code for the human readable output (as cweave does in cweb) and reassemble the code for the compiler (see ctangle).
Let’s look at an example:
@* Say Hello.
When you learn a programming language it's a good manner to first say hello to
the language, by making the computer say hello to the world. Of course this can
be done in several ways, but the most common go way is to use the `fmt` package.
@<say hello@>=
fmt.Printf("Hello, world!\n")
@* Appendix A:Technical frame of the program.
In the appendix we can assemble the sections.
@go
package main
import "fmt"
func main() {
@<say hello@>
}
I used a syntax similar to cweb, to give some hints about how this is done. What both parser basically have to do is to search the code for @
characters. The precompiler for the human readable output will format the sections and pretty print the code, while the precompiler for the go compiler will reassemble the code sections in a way the go compiler wants it, beginning with the first @go
section found in the source text.
From my experience, once you learned to write code this way, you don’t want to miss it, because it also restuctures the way you think about the problem you want to solve with the code.
It is a pain that the only language I have the full set of literate tools at hand is plain C, though you can massage the system a bit, to do C++ or Objective-C.
I really would appreciate something similar for Go! If I find some time, next months, I will start such a tool, but I first want to check what the go community thinks about this approach and how we may need to modernize the syntactical structure, to better match the look-and-feel of go code.