Up to Main Index                            Up to Journal for August, 2018

                     JOURNAL FOR SUNDAY 19TH AUGUST, 2018
______________________________________________________________________________

SUBJECT: Improved recordjar tests and documentation
   DATE: Sun 19 Aug 22:12:32 BST 2018

After the fiasco with my Nokia and the June and July security updates[1], the
August security update was downloaded and installed without any fuss :)

I’ve completed writing tests for the recordjar.Write method and added some new
tests for the recordjar.Read method. It took longer than expected as I thought
I had found an issue, but I was wrong and everything was fine.

I have rewritten the recordjar package documentation, recordjar/doc.go, so
that it is more comprehensive and accurately describes the implementation.
This includes all of the differences to the implementation described by Eric
Raymond[2] in “The Art of Unix Programming”, chapter 5.

Updating the package documentation has been very rewarding. On quite a few
occasions I’ve written something, and then had to write additional tests to
confirm things really work that way. For example blank line handling. If you
have a record with only a free text section do you need a separating blank
line? What if a comment precedes it? In both cases no, you only need a
separating blank line to separate a free text section from a field section,
which is logical but I had to double check. Comments on the new documentation
appreciated: diddymus@wolfmud.org

I’ve also updated the documentation and comments to consistently use ‘free
text section’ instead of ‘freetext block’ or ‘free text block’.

All of these changes are on the public dev branch.

I’ve also made a note[3] of a change I want to make to recordjar/Write method.
At the moment field names are lowercased and then the first rune is
uppercased. This results in field names like ‘Name’, ‘Aliases’, ‘Onaction’,
‘Onreset’ and ‘Oncleanup’. Those last three really bug me. Looking at the
reference implementation, a better idea would be to use a hyphen for a space,
so ‘Onaction’ becomes ‘On-action’. Then the character after any hyphen can
also be uppercased automatically, resulting in ‘On-Action’, ‘On-Reset’ and
‘On-Cleanup’ for the field names. What do people think of that idea? Comments
welcome.

Next up will be writing tests for the recordjar/encode and record/decode
packages.

I’ve spent some time checking out Go 1.11 RC1 with WolfMUD. Had a slight
problem after hitting this issue:


  runtime: out of memory while executing make.bash #26523
  https://github.com/golang/go/issues/26523


I’m using a Pi Zero W as in the reported issue. However I have 481Mb available
RAM and swap in zram. Increasing the memory allocated to zram for swap from
64Mb to 128Mb was enough to allow a successful compile.

--
Diddymus

  [1] See journal for 6th August: 6.html

  [2] Eric Raymond, “The Art of Unix Programming”, chapter 5:

        http://www.catb.org/esr/writings/taoup/html/ch05s02.html

  [3] I log bugs, todos and fixme notes using the ‘TAG(name):’ convention.
      This allows for easy grepping of the source for ‘BUG|TODO|FIXME’. It
      also show up in ‘go doc’, although ‘godoc’ seems to need an additional
      parameter for codetags other than ‘BUGS’. For example:

        godoc -http=:6060 -notes="BUG|TODO|FIXME"

      I have an old, unmaintained TODO list, I guess I should convert the
      three items it contains into code comments for better visibility,
      tracking and maintainability.


  Up to Main Index                            Up to Journal for August, 2018