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.
- 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.
- 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.
- 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.