A Rusty Return

Recently a fellow Xebian published an article about becoming a documentation ninja through the use of the tool mark to generate smart Confluence documentation. Last year as a in-between assignment project I wrote a more space/multi-page oriented version of the same functionality in Rust, so naturally I suggested he should have a look and let me know what he thought.

He was pretty excited by the improvements that I’d made, mostly around the cross page linking, move detection and automatic image attachment. He also pointed out a few places where there were missing functionality - which he’d recently added to Mark via pull request himself.

Now, I hadn’t really looked at the project since I wrote it - I hadn’t had a cause to yet, although I had considered a few places where it would have helped. No, instead I was writing documentation directly in Confluence, which I’m not going to lie, has become a lot less pleasant now that Confluence is begging you to use AI every where you look.

That aside, I decided to have some fun to try to implement the feature Joris had added via PR to my own project - page emojis. These emojis would appear beside the title in both the space tree and in the page itself:

Should be a relatively simple API call, some shortcode parsing from the markdown frontmatter - easy peasy.

I am not ashamed to say that coming back to Rust after a year away was not the easiest. To be fair, I had used it for a little over month - not really enough time to really burn the patterns into your brain.

Yet there were two things that really stood out to me as a returned with a fresh perspective.

Data Layout vs. Data Modelling #

Rust, despite the borrow checker, really benefits from you thinking about how you’re going to lay out (and not necessarily model) your data. What I mean by this is that you need to think more in terms of transformation of data, more than the relationships between data. This is a big difference if you’re more of the modelling type (and by this I generally mean object orientation). It doesn’t mean that it can’t be done, it’s just a different way of thinking about things.

Unit Testing for Future You #

Unit testing really is worth it, not just by getting it right when you first write things, but knowing its right once you come back. I am pretty proud of this test suite:

test result: ok. 57 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.05s

This is not test driven code, but more demand driven code… I try to test the common cases for things I know I often mess up - things that have multiple combinations through nested-if-else blocks, for example. This gives me confidence about the core logic, that I then fix and correct as I manually test it as well. Exploratory testing is still 100% required, imho.

Anyway, this was supposed to be a post promoting a new feature in my markdown-to-confluence tool, and what it was like to come back to a Rust project after a year away. It was fun and interesting. I might even fix up a few more issues. Maybe even write some proper documentation for the tool.

Oh the irony.