NOTESMACHINE: THE LAYOUT PROBLEM

As I'm building out the design and model of Scarlett (which seems dangerously likely to get renamed 'Notesmachine' at the rate I'm going), I've hit one of those architectural things that annoys me. Allow me to ruminate on the problem.

As mentioned in the previous post, the traditional organization of any notes system is that of the Forest; each Box contains notes, some of which are the roots of trees, and the rest of which are nodes of the tree leading to leaves, which are notes that have no descendant notes.

On the other hand, I have interests that are orthogonal to that design. Let's take them in order:

A WILD INSIGHT INTO MY CAREER

There's a difference between "What you do" and "What you really do."

An I mentioned earlier, I'm looking for work. Given that I'm not working, and doing the looking only takes half the day, I'm spending the other half of the day diving back into Rust. Those two events came together in a conversation I had today with a "career coach" in an unexpected way.

My career coach loves my elevator pitch:

NOTESMACHINE: ARCHITECTURAL DESIGN RECORD

If you're like me, you have more than one hard-drive full of random stuff: notes, PDF files, Epub files, ZIP and TAR files, GIT repositories of (mostly incomplete) projects, and so on and so forth. Also, if you're like me, these projects devolve into a bunch of different areas: my professional life, my artistic and creative life, my open-source footprint, my personal life like my kids and my wife, the infrastructure of my life like the current projects in home maintenance, and in my case an imperial buttload of recipes.

My Rust has gotten rusty, so to speak, so I've decided to try and write something to help me manage it. This post is mostly me rambling about what I'm going to write, gods help us all, and how I want to manage writing it.

Basically, I want a knowledge base. That's it. That's the simplest thing possible. In fact, pretty much what I want is some kind of Roam clone, but one with extra superpowers.

I'm going to use a term that doesn't exist in the real world: "egotonin." Egotonin is a mythical substance that gets used when you're exerting willpower; it is the thing that is depleted in the concept of ego depletion.

So lets talk about Knowledge Bases.

System administration

ORGANIZING YOUR BASH PATH

If you've ever looked at your .bashrc file and wondered how the heck it got so weirdly out of control, look no further than the slow migration of "local changes" to the .local folder, and the number of language– or framework-specific environments that are now kept there.

There's much to recommend this move, not the least of which is decluttering the $HOME directory. But my biggest pet peeve was the $PATH variable, which seemed to just grow and grow in my .bashrc file into an unreadable string. I've decided to fix that. Here's how.

Personal

HOMEWORK ASSIGNMENT: WHAT I LEARNED

I just finished one of those take-home programming assignments that companies are sending out these days in lieu of whiteboarding exercises, a process that I'm genuinely thankful for. Whiteboarding is just a way to stress someone out; it doesn't prove anything (except excessive cleverness, sometimes). We work with a fully immersive IDE (even if Emacs is still making itself difficult in that regard), we work with StackOverflow available, and we work surrounded by books, notes, and cheatsheets. We even work with our fellow workers on the other end of Slack and Zoom.

A lot of what I did was "re-learning," but it's always good to go over it again, just in case. Here's a lot of what I absorbed:

Personal

A NEW LOOK FOR A NEW PHASE

You may have noticed a few changes in the place. I've gone to an all-static engine. I chose Zola, because although it wasn't sufficient for what I wanted out of my story site, it's perfectly fine here.

Rust

WORKING ON SCARLETT 2.0, AND THE SQL IS FUN!

I’ve been hacking on a secret project that I’ve had in the works since, oh grief, the first check-in was:

<code>commit ccb93ca5f2b256babfa0f2ef9110ac0ac4019527
Author: Elf M. Sternberg <elf.sternberg@gmail.com>
Date:   Mon Feb 4 23:03:01 2013 -0800

Initial check-in for Scarlett.</code>

The original project (yes, it’s named “scarlett”, deal with it) was in a combination of Python and Javascript, with Backbone as the front-end. It was, quite frankly, a terrible project, but it did what I wanted it to: it kept track of my notes. I have a directory named “Wiki” into which I dump markdown files, and have for years, and all it does is give me a slightly better UI for ‘grep,’ but it’s better than nothing.

IF YOU CAN SPOT THE LEAK IN AN ABSTRACTION, YOU CAN DESIGN ALMOST ANY PROGRAM

I’m going to use the word “abstraction” in two different ways, but bear with me for a moment and consider this:

  1. Every startup is based on an insightful abstraction of a complex idea.
  2. Every software abstraction is leaky in some critical way.

Uber is an abstraction of taxis. How do we abstract “what a taxi is” using the higher-level technologies we have now? Amazon is an abstraction of mail-order sales, which have been around since Sears pioneered them in 1897. Google is an abstraction of card catalogs and yellow pages. And so forth.

In programming, an abstraction is a higher-level description of a process or mechanism that is designed to hide some level of complexity behind a simple set of controls. The menu on a word processor hides the complexity of the software behind it. The API we use to “log in with Facebook” or “log in with Google” hides the complexity of securing your authorization across multiple websites and applications while revealing your identity to advertisers.

Design

IS AGILE COMPATIBLE WITH CLEAN CODE?

I’ve been through Agile training several times before at different jobs, and the current job is no different. June is Agile Training Month, and since I started last September I’m obliged to go through this again. Previously, we had a Clean Code Training period that lasted two months, and I realized today why I’m having such a hard time with the Clean Code part of the training.

The Agile process says that the product should have value to the customer at the end of the first month, and that the value to the customer grows as the development team puts more intellectual work into building out its functionality.

Programming

REVIEW: CLEAN CODE, BY ROBERT MARTIN

It might seem like I’ve been harsh on Robert Martin’s Clean Code for the past couple of posts, and that’s valid. I have been. It’s such a good book, full of strong advice on any number of topics.

It’s just that it feels old. Programming is a young discipline in the world, probably one of the youngest, and one of the most consequential. It changes with absurd speed, and everyone in it struggles to keep up. Clean Code came out in 2006 and already there are dusty corners within that feel out of date, even irresponsible.

Engineering notebook

IF YOU'RE A SENIOR DEVELOPER, YOU HAVE TO ACCEPT SOME WET CODE.

In some programming languages there is an essential, powerful tension between two common pieces of advice: Don’t Repeat Yourself and Meaningful Names over Code Comments. Both are really good pieces of advice.

“Don’t Repeat Yourself” (DRY) means that if you can find an abstraction that allows you to avoid repetition in your code, you can remove the need to debug multiple code blocks if you find an error, and you can test the abstraction more reliably and more efficiently. The opposite of DRY is, of course, WET, “Written-out Every Time.”

“Meaningful Names over Code Comments” means that if you have strong, descriptive names for classes, functions, and variables, then code comments are often not merely unnecessary but possibly harmful as they drift out-of-date with the actual content of the code.

At my ${DAY_JOB}, I ran into this conflict in a big way. This example is in Python, but it applies to any language with metalanguage capabilities, which includes Ruby, Lisp, Rust, and even C++.

DEAR "CLEAN CODE" FANBOYS: SQL IS A PROGRAMMING LANGUAGE.

One thing that irks me beyond all reason is Robert Martin’s seething dislike for databases. In every presentation he’s ever given, the one thing he’s sneered at is people who “write their code around a database.” In one of his lectures he says, “I don’t want to see a database in your design. I want to see the objects you’ll use, and I want their names and locations in your project file to reflect how you’ll use them.”

This is probably the lousiest piece of advice he’s ever given. Because let me say this once and simply:

SQL is a programming language, not a storage mechanism.

"CLEAN CODE" IS THE CODE SMELL OF A MISSING LANGUAGE FEATURE.

Uncle Bob has a passage early in his book where he criticizes the function below, calling it “too long” and “missing context”. I agree that it’s cluttered and hard to read, but his representative solution is, frankly, absurd. He turns this into a C++ class with static methods for providing the modifiers to the text, all the while ignoring the huge elephant in the code: it does two things.

Programming

LAB NOTES, FIRST TWO WEEKS OF JANUARY: PAMSEAM W/LATTICE EXPERIMENTS

Lab notes for the first two weeks of January.

I’ve been fiddling with a branch of the PamSeam project named Lattice in an effort to streamline the base and speed up the runtime. There are three algorithms enabled and all of them have similar processes. The basic engine is also very slow, with lots of large allocations and copying the image over and over.

MATH IS NO HARDER THAN DRAWING

I recently read an article on the economics of ancient Rome that suggested that, while the written arts, especially those that involved education or erudition, were highly valued, the visual and performance arts were not. The visual arts, especially, were regarded as the work of the lowly and demeaned, as almost all the arts we see from Rome, Pompeii, and Herculaneum, all of the frescoes and mosaics that have survived to this day, were made by slaves.

MY NEW JOB REQUIRES I AVOID LEARNING SOME THINGS!

I realized the other day that my role in my current job requires that I do something very, very strange, as far as I’m concerned. I realized there are some things I have to avoid learning, and I have to avoid them quite strenuously. I have to know they exist, but I have to not know any more than that.

One of my tasks is to help software engineers write their own tests and documentation. To be good at that, I have to help them focus on the kind of documentation they’re writing, and at the moment that documentation is “pager duty” how-tos: short instructions for how human beings must respond to problems and issues with the running system.

Programming

GREAT CHESS PLAYERS DON'T SEE THE PIECES, THEY SEE THE BOARD. GREAT PROGRAMMERS NEED TO LEARN FROM THAT.

OPEN SOURCE PROGRAMMERS MUST KEEP THE PROMISE OF THEIR PREMISE

GENERALISTS BEAT SPECIALISTS MOST OF THE TIME, BUT TRY TELLING HIRING MANAGERS THAT

WHILE WATCHING AN UNCLE BOB LECTURE, I FIGURED OUT WHERE THE CLOUD ALL WENT WRONG