Up to Main Index Up to Journal for May, 2018
JOURNAL FOR SATURDAY 5TH MAY, 2018
______________________________________________________________________________
SUBJECT: On testing and examples in Go
DATE: Sat 5 May 17:39:20 BST 2018
Oh dear, the weather is warming up and turning nice. That means less time for
WolfMUD and more time spent in the garden mowing lawns, cutting hedges and
weeding *sigh* :(
What have I been up to recently? I’ve tweaked the website a bit. The colours
have been changed to a dark theme. The font has also changed from “Go Mono” to
“Robot Mono”. I found Robot Mono at larger sizes to be more pleasing, although
the quotes ‘’ and “ ” are not as nice as before.
Will the changes stick? I’m not sure. I might revert the font back to Go Mono.
On the coding front I’ve been testing mostly. The Uncomment function, for
removing in-line comments in strings, has moved into the text package — as it
can uncomment any text and not just regular expressions. Tests have been added
for the function too.
In the recordjar package I’ve commented the splitLine regular expression and
included new tests for splitLine. The compareJars testing helper function has
been rewritten to be much simpler. All of the recordjar.Read tests have been
rewritten and cleaned up.
It has taken a while to sort out testing so that it’s in a state I’m happy
with. Before, it was just a hodgepodge mess. So I studied the Go source code
for some inspiration. I’m now using packagename_test for black box testing.
Test methods are named consistently, and sub-tests are being used.
For the text.Uncomment function I’ve included an example_uncomment_test.go
file. I’m still in two minds as to whether this is a good idea or not.
Normally I would write some code in the function comments, such as:
// Uncomment takes a string with comments and returns the string with
// whitespace and comments removed. Comments are expected to be delimited
// with a '#' character followed by at least one whitespace. When a string
// is uncommented each line will be stripped of leading and trailing
// whitespace. Comments will be removed from the '#'+whitespace separator
// to the end of the line.
//
// The prime motivation for this is to allow regular expressions to be
// commented inline - in raw string literals - similar to Perl's /x
// modifier. For example these two are equivalent:
//
// var uncomment = regexp.MustCompile(`(?m)(?:\s*#\s.*$|^\s+|\s*\n)`)
//
// var uncomment = regexp.MustCompile(text.Uncomment(`
// (?m) # Match in multi-line mode
// (?: # Start a non-capture, alternating group
// \s*#\s.*$ # Match line ending in a '#' delimited comment
// | # OR
// ^\s+ # Leading whitespace
// | # OR
// \s*\n # Optional trailing whitespace, followed by a new line
// ) # End group
// `)
//
func Uncomment(re string) string {
return uncomment.ReplaceAllLiteralString(re, "")
}
That way you can use ‘godoc’ and a web browser, ‘go doc’ on the command line
or view the source code and see the documentation and the example at the same
time, all in one place. Instead I now have in uncomment.go:
// Uncomment takes a string with comments and returns the string with
// whitespace and comments removed. Comments are expected to be delimited
// with a '#' character followed by at least one whitespace. When a string
// is uncommented each line will be stripped of leading and trailing
// whitespace. Comments will be removed from the '#'+whitespace separator
// to the end of the line.
//
// The prime motivation for this is to allow regular expressions to be
// commented inline - in raw string literals - similar to Perl's /x
// modifier.
func Uncomment(re string) string {
return uncomment.ReplaceAllLiteralString(re, "")
}
Along with an example_uncomment_test.go:
// Example of a commented regular expression and uncommenting it.
func ExampleUncomment_simple() {
text := text.Uncomment(`
(?m) # Match in multi-line mode
(?: # Start a non-capture, alternating group
\s*#\s.*$ # Match line ending in a '#' delimited comment
| # OR
^\s+ # Leading whitespace
| # OR
\s*\n # Optional trailing whitespace, followed by a new line
) # End group
`)
fmt.Println(text)
// Output: (?m)(?:\s*#\s.*$|^\s+|\s*\n)
}
The upside is that the example is now included in testing.
The down side is that you now need to run godoc locally to see the example
along with the documentation for the function. Notice I said ‘godoc’, as far
as I am aware you cannot view examples using plain ‘go doc’. You also cannot
run the example code in a browser, like you can examples in the standard
library documentation. If you are looking at source code you need to browse
both uncomment.go and example_uncomment_test.go to get the full picture.
This to me is a lot of down sides for a single up? Am I missing a trick here?
I’ve put the changes out on the public dev branch. If anyone has a moment, I
would welcome any feedback on the testing, examples and site changes:
diddymus@wolfmud.org
--
Diddymus
Up to Main Index Up to Journal for May, 2018