Putting Pen To Paper

Putting Pen To Paper

By | | Comments 0 Comment

I spent some time today chatting with an early career colleague who’s looking towards a future career in the dark arts software development. Being the kind of person that enjoys the sound of my own voice, I enjoy these opportunities to pontificate. One piece of advice I routinely give is that good engineers write well, and developing this skill will pay itself back with copious dividends.

However, that shouldn’t be read to mean that quantity trumps quality. Far from it, keeping things brief is usually more difficult than not (I know I’m bad at rambling, kinda like I am now). Which is why I found this little article on the value of the humble readme such valuable advice.

The other day I published a blockchain solution on Github, and while I’m pretty proud of the code, the readme is in bad shape (as of today at least). For my next project (a refactoring of the core of this solution into a reusable CDK construct) I think I’m going to write the readme first, as the above article suggests. We’ll see how it goes!

Hodgepodge Advice

Hodgepodge Advice

By | | Comments 0 Comment

I’m a sucker for lists that contain pithy nuggets of truth. Here’s two great ones I found this week:

Some of my favorite statements, in no particular order:

If you don’t have a good grasp of the universe of what’s possible, you can’t design a good system

Every system eventually sucks, get over it

Software engineers should write regularly

Always strive to build a smaller system

KISS, don’t be afraid, and boring > cool

The bottleneck is almost always the database

Doomed To Repeat It

Doomed To Repeat It

By | | Comments 0 Comment

Technologists are particularly susceptible to recency bias. It’s one reason why I try to read older computer science literature from time to time (especially work from the 60s and 70s). The Mythical Man-Month is my canonical example; it should be required reading for everyone who works with technology. The Psychology of Computer Programming contains timeless truths of what it takes to lead a team of software engineers. Donald Knuth’s The Art of Computer Programming is a dense, three volume work, but much treasure lies within. I’ve only finished the first book, but I came away with tremendous respect for the geniuses that paved the way for us fortunate souls who have IDEs, fast compilers, and gigabytes of RAM.

Today I read On the Criteria To Be Used in Decomposing Systems into Modules, a research paper by D.L. Parnas of Carnegie-Mellon University, published in 1972. While the details of the middle section weren’t terribly interesting, it’s the bookends of introduction and conclusion that impressed me. The benefits of two-pizza teams were clearly understood fifty years ago, for example (“separate groups would work on each module with little need for communication”) and the paper lays out a novel approach to decomposition (to me, at least):

“We propose instead that one begins with a list of difficult design decisions or design decisions which are likely to change. Each module is then designed to hide such a decision from the others.”

The above resonates with prior posts I’ve written on abstractions, especially Out of Sight, Out of Mind. If the goal of abstraction is to hide difficult detail, we ought to modularize with that goal front-and-center.

The Butterfly Effect

The Butterfly Effect

By | | Comments 0 Comment

I was privileged to have access to computers from an early age, from the humble TI-99/4A of my early elementary years to a snappy Pentium in high school (can’t remember the exact model, but it was pretty expensive; perhaps the 133MHz version?) The influence this access had on my life cannot be overstated.

Young Jud on TI-99/4A
Train up a child in way they should go

Now that I’m firmly in middle age, and on a career path where I’m regularly evaluating technical talent, I’m reminded of that privilege, and how so many didn’t have it then, and some still don’t have it now. How much untapped potential there must be within these groups!

If we’re going to overcome the lack of diversity in tech, it starts with access; early access, when life-long perceptions are formed. As the saying goes: the best time to plant a tree is 25 years ago, but the second best time is today. Gotta get planting!

Takin’ Care Of Business

Takin’ Care Of Business

By | | Comments 1 comment

Love them or hate them, ticketing systems like Jira or Asana are an essential part of modern software engineering. Misuse is rampant, but wielded well, ticketing systems align teams around common goals, unburden them from pointless status meetings, and unlock accelerated development with better accountability and fewer defects.

What are some ticketing best practices, you ask? I have thoughts:

  • Work of any significance should be captured in a ticket. My rule of thumb is anything that takes longer than a few hours.
  • Tickets are not a substitute for good requirements and design documentation. Instead they should capture specific tasks to be accomplished, including links to other docs as needed.
  • Writing tickets is not only the responsibility of the team lead or product manager; a team should own its ticket board. If the current set of tickets does not match the reality of what is being worked on, make it so be rewriting, breaking up, and deleting tickets as appropriate.
  • Being assigned a ticket is a form of promise. It says to the team “I will accomplish this task in this amount of time.” Each engineer should thoroughly understand all of the tickets assigned to them, proactively seeking out guidance if they don’t, and making clarifying edits as needed.
  • Know how metrics such as velocity and completion dates are computed. Their value is only as good as the ticket data used to calculate them (garbage in, garbage out), so ensure values like story points are accurately tracked.
  • Avoid Bricklin’s Law by embracing healthy use of a ticket system, and others won’t feel the need to add more status tracking. Done perfectly, it renders other status checkpoints redundant, maybe even those daily standups you dread.
  • Finally, tickets are a means, not an end. Don’t lose sight of your ultimate goals. If your ticketing process isn’t helping you achieve those goals, change it.

The above list is far from exhaustive. Any other suggestions out there?

There’s Gold In Them Thar Hills

There’s Gold In Them Thar Hills

By | | Comments 0 Comment

In my conversations with fellow engineers, git comes up quite a bit. I find myself regularly giving advice both tactical and strategic on its effective use. Learning it in detail is a force multiplier, but few people do. Part of the problem is that training materials are all over the map.

Which is why I was so pleased to discover Git from the inside out. Without question the best introduction to git I’ve come across. It perfectly balances teaching basic commands while also explaining what’s actually happening. Despite having used git at a fairly advanced level for 10 years, I still learned some new things, for example that each git add creates an immutable blob object that is retained for a while even if you git add the same file again, and even if you never commit it. Also that it’s pretty easy to decode raw git objects should you ever need to; here’s a script I wrote to do just that, if you’re curious.

I’ve said before that abstractions are valuable, but they’re not excuses to avoid learning internals, because critical information lies beneath the surface. At the risk of pretentiously quoting myself:

When things go wrong, the engineer must descend into the particulars, and an inability to minimally reason about, if not fully grasp, what lies beneath an abstraction can prove fatal to the debugging process.

I didn’t write the above with version control in mind, but I surely could have. Engineering organizations are full of developers who run stuck the moment a git command fails. You don’t have to be that developer!

Be Kind, Not Right

Be Kind, Not Right

By | | Comments 0 Comment

Several months back I read The Phoenix Project, a tale about how one company changed its IT culture to great success. I found the advice mostly good, and the idea of dishing it out in narrative form kept things interesting, though I’d hardly call it a page-turner.

However, one aspect really bugged me about it: the “guru” character Erik is a real piece of work. Talking down to his colleagues. Deliberately getting names wrong. Assuming his own body odor smells of perfume, as the Amazon leadership principle warns against. In the actual world, without kindness, it doesn’t matter if you’re right all the time, no one will listen to you. This is just as true in the realm of technology work: ever been told to RTFM and felt like an idiot? You’re not alone. I have to fight being that kind of jerk, but it’s a fight worth having.

And of course it really shouldn’t be that hard of a fight. Just do the little things: be on time, be responsive, be quick to listen and slow to criticize. Be patient. Treat others as they wish to be treated.

Oh, and learn your colleagues names, both spelling and pronunciation. It’s a basic gesture of respect that goes a long way.

I Appreciate You

I Appreciate You

By | | Comments 0 Comment

Technology-related work, like all work, is primarily a social endeavor. It’s surprising that so little effort goes into preparing aspiring technologists about this side of the business, especially given our propensity to be singularly bad at it. Hence this article.

Along related lines, I found the suggestions in What Makes a Great IT Consultant completely applicable to a broader set of technology roles, and would highly recommend it.

I’ve also finally started digging into The Architecture of Open Source Applications; it’s been hit and miss, but more of the former, so definitely worth the time investment. A statement that jumped out at me today (from the chapter on Eclipse) was that an API is a social contract just as much as it is a technical one. I like that way of looking at it; seems a natural corollary of Conway’s Law.

In tangentially-related news, season 2 of Ted Lasso comes out today. You should watch it.


Slip Of The Finger

Slip Of The Finger

By | | Comments 0 Comment

Don’t run your tests with production data. Just don’t. Otherwise, your customers will end up with delightful emails like this:

In jobs past I was pretty cavalier with production data. I was never part of a major incident, but that was more due to luck than strong security controls and separation of concerns. Really thankful that my current employer takes this stuff as seriously as it deserves.

Mount Rushmore

Mount Rushmore

By | | Comments 0 Comment

I wish I had the time and talent to write like Joel Spolsky. He’s one of my favorite people in the public sphere of software engineering. Here’s a couple articles I read yesterday, they’re both oldies but goodies:

  • Making Wrong Code Look Wrong – I’ve never been of fan of the “data type prefix” in variable names, so I was biased going into this discussion. But I was pleasantly surprised to hear the actual history of Hungarian Notation and that misuse of it was based on a misunderstanding of “type” vs “kind”.
  • The Law of Leaky Abstractions – I’ve talked about abstractions before, they’re a central concept to the art of software development. Getting them right is hard; in fact, it might just be impossible.

You should check out Joel’s whole blog. It’s great.