We are approximately 3.5 months since lockdown started because of the COVID-19 pandemic, and the last time I blogged was mid November - which is incidently around when the first reported cases of COVID-19 started, so I’m not ruling out the possibility that it is somehow related, but I figure I write about some stuff I learned.

1. I wrote a code interpreter! I wrote it in C# and basically ~copied~ learned from Lisperator. Nothing special, it only supported integers and floats and variables. I added support for negatives! wow! Seriously though, it was fun to write, and I learned about taking a complicated idea and breaking those down into smaller problems.
2. I tried to write a powershell formatter. There is a fair bit of overlap with the above project. Lucky there is a built-in powershell parser that spits out both a series of tokens, and an AST. I started with the token approach, but moved to using ASTs. I started working on this because we write a lot of Powershell code at work, but we didn’t use any code formatter. It turned out that two formatters exist - PowerShell Beautifier and cleverly hidden inside the PSScriptAnalyzer is Invoke-Formatter. The former has some issues though.
3. I grabbed an AKAI MidiMix and have been playing with it. My goal is to make some sort of poor-man’s reggae preamp - though a lot less cooler and much more limited. I’ve only really just started with it, and I have no idea what I’m doing.

I haven’t bothered putting any of these projects under source control as I never planned on releasing them. I think having throw-away projects provides a lot of value even if they never make it outside my machine.

So the documentation wiki at our work is broken. Well it’s actually works just fine, but it’s neglected and unloved. People write documentation for various reasons, things change, and nobody updates the documentation (either they forgot, or the people making the changes didn’t even know it existed). For us, we have a lot of documentation that hasn’t been touched for years. No-one is sure what’s still relevant. So there is talk about moving docs from the wiki to our GitHub. While not a bad idea in itself, it seems to solve none of this problem of neglected documentation.

So what’s the answer? Do we need more discipline? Should we make documentation a first-class citizen the same way we treat tests?

I want you to consider a really contrived example:

class Foo {
	public int add(int left, int right); // implementation is left as an excercise for the user
}

Suspend your disbelief some more and pretend this thing had documentation (I’m pretending this is what documentation even looks like)

## Class Foo
### add(int,int) -> int
Adds two numbers

Here’s my idea: So what if the documentation instead looked like this:

## Class Foo
### add(int,int) -> int
<!-- assertion: foo.lib Foo.add 931606baaa7a2b4ef61198406f8fc3f4 -->
Adds two numbers

In other words, I had a tool that could:

• calculate the hash of a function
• validate that Foo.add in foo.lib matches the expected assertion

So the idea being that, if Foo.add ever changes the hash would change and the documentation will be invalid. Now this isn’t great of course, because improvements to the function (ie. bounds checking) would cause a whole bunch of assertions to fail. Not ideal. So what if we tied it to tests? Of course this thing would have tests

[Test]
public Add_TwoNumbers_ReturnsResults() {
	int results = m_foo.add(1,2)
	Assert.AreEqual(3, results);
}

## Class Foo
### add(int,int) -> int
<!-- assertion: footests.lib SomeClass.Add_TwoNumbers_ReturnsResults 557c0271e30cf474e0f46f93721fd1ba -->
Adds two numbers

Bounds checking would be a different test, so the hash wouldn’t change.

It’s an idea. I don’t have a working concept yet. There are also many pitfalls to this approach. Refactoring code might introduce a bunch of failures. Not everything can be captured in code, such as architecture diagrams. Maybe an interesting weekend project over the Christmas break.

(One test to know whether you truely understand something is by trying to explain it. Please be aware I don’t truely understand GPG)

If you read my last post on GitHub commits you will probably be completely unsurpised that I (sometimes) sign my commits now. I mainly do gpg signing at work using a YubiKey. The way I have it setup is I created a subkey, and exported that subkey to my YubiKey. I also put an expiration of 3 months on my subkey. The idea being that, if you don’t do this often enough you’ll forget about it.

Soooo 3 months later and (surprise) I definitely forgot how I update my expired subkey. I eventually figured it out, so here it goes:

1. Take your YubiKey and put it aside
2. Go to your machine that has the master key.
3. run gpg2 --edit-key cesar
4. Select the key you want to update: key 514EBCC933245B8E
5. Type expire and follow the prompts
6. Export your key with the new expiration dates gpg2 --export cesar
7. Import your key into your work computer

I spent a lot of time between steps 4 and 5. My understanding was that my GPG key was on the YubiKey, and I was trying to import the key into the YubiKey. This is not true. My signing private key is on the YubiKey. It does not have the concept of expiration.