Keeping Track of your Technical Debt

The impact of technical debt

Over the years the concept of "technical debt" has become a phrase that can generate anxiety and a lack of trust, as well as setting up developers and their managers for failure. The metaphor might not be perfect (Ralf Westphal makes a strong case for treating it like an addiction), but I feel it's pretty apt if you think of the story of The Pied Piper of Hamelin - if you don't pay the piper promptly for keeping you alive, he'll come back to steal your future away.

Maybe I'm being a bit dramatic, but I value my time on this planet and over the course of two decades as a software developer in various sectors of the industry I have (along with countless others) paid with so much of my own precious lifetime (sleep hours, in particular) for others' (and occasionally my own) quick fixes, rushed decisions and hacky workarounds that it pains me to even think about it.

It's almost always worthwhile investing in doing things right the first time, but we rarely have the resources to invest and we are often unable to accurately predict what's right in the first place.

So let's at least find a way to mitigate the harm.

Why TODOs don't help

The traditional method of initiating technical debt is the TODO. You write a well-meaning (and hopefully descriptive) comment starting with TODO, and "Hey, presto!" you have a nice, easy way to find all those little things you meant to fix. Right? Except that's usually not the case. We are rarely able to make time to go looking for more things to do, and even when we can, with modern software practices it's unlikely that searching across all of our different repositories will be effective.

What generally ends up happening, then, is that we only come across TODOs by coincidence, when we happen to be working with the code around it, and the chances are that it'll be written by a different developer from a different time period and be explained in... suboptimal language.

"Why hasn't this been done?", you may well ask.

"Leave that alone! We don't remember why it works," you may well be told.

Track your technical debt with this one simple trick!

No matter the size of your team (even a team of one), you should always be working with some kind of issue tracking software. There's decent, free software out there, so there's really no excuse.

The fix? All you need to do is log a ticket for each TODO. Every time you find yourself writing a TODO, and I mean every single time, create a ticket. In both the ticket and the TODO comment, explain what you're doing, what needs to be done, why it needs to be deferred, and how urgent completing the TODO task is.

Then reference the ticket in the TODO comment.

This way you'll have a ticket - which I like to think of as an IOU - which can be added to the backlog and remembered when grooming and planning. This also provides the developer who encounters the TODO in the code a way to review any details and subsequent conversations in the ticket.

One interesting side effect of this approach? I often find that it's more effort to create the TODO ticket than to do the right thing in the first place, which can be a great incentive for the juniors to avoid the practice.

Another?

Indiana Jones No Ticket GIF from Indianajones GIFs

After establishing with my team that I will not approve a TODO unless there's a ticket attached, I must admit... I do sleep just a little bit better at night.

simple-free-encryption-tool frontend now handles files

If your browser supports it, simple-free-encryption-tool can now encrypt and decrypt any local files you wish!

Handling emails with node.js and Mailparser

After sorting out mail forwarding and piping emails with postfix, I then needed to understand how to handle emails being POSTed to an API endpoint.

To parse an email with node.js, I recommend using Mailparser's simpleParser. I'm using express with bodyParser configured as follows:

app.use(bodyParser.json({
 limit : config.bodyLimit
}));

In your handler:

const express = require('express');
const router = express.Router();
const simpleParser = require('mailparser').simpleParser;

or

import { Router } from 'express';
import { simpleParser } from 'mailparser';

and then

api.post('/', (req, res) => {
    simpleParser(req)
        .then(parsed => {
            res.json(parsed);
        })
        .catch(err => {
            res.json(500, err);
        });
});

Mailparser is excellent, and documented, but the documentation assumes that we're familiar with the email format. Fortunately, oblac's example email exists for those of us who aren't!

To test, send the example email to the endpoint via curl:

curl --data-binary "@./example.eml" http://your-domain-name/api/email

or Postman (attach file to "binary").

And we're good to go!

Mail forwarding and piping emails with Postfix for multiple domains

The past few weeks I've been learning about mail servers, and the biggest takeaway for me is that it's generally worth paying someone else to handle the headache. As usual, the obstacles to configuring a mail server correctly are primarily in the lack of useful documentation and examples, so I'm putting this down here in the hopes that it'll be helpful to like-minded constructively-lazy devs.

While I'm happily using mailgun for mail sending (after much frustration I threw in the towel trying to integrate DKIM packages with Postfix to get my outgoing emails secured) I was certain that I could at least have my mail server handle mail-forwarding for my multiple domains, and while that proved to be fairly straightforward I then tumbled down a rabbit-hole trying to get Postfix to pipe certain emails to a node.js script for processing.

Here are the steps you'll need to take:


• Set up your A and MX records for your domain, the A record @ pointing to the IP address of the server you’re going to be receiving emails on and MX with the hostname @ and the value 10 mail.your-domain-name
  
  If your mail server is not the same as your primary A record, simply create an additional A record mail pointing to the correct IP address.
• sudo apt-get install postfix
  Select "Internet Site" and enter your-domain-name (fully qualified)
• sudo vi /etc/postfix/main.cf
  • Add mail.your-domain-name to the list of mydestination values
  • Append

    virtual_alias_domains = hash:/etc/postfix/virtual_domains
    virtual_alias_maps = hash:/etc/postfix/virtual

    to the end of the file
• sudo vi /etc/aliases
  

  curl_email: "|curl --data-binary @- http://your-domain-name/email"

• sudo newaliases
• sudo vi /etc/postfix/virtual_domains
  

  example.net   #domain
  example.com   #domain
  your-domain-name   #domain

  (the #domain fields suppress warnings)
• sudo postmap /etc/postfix/virtual_domains
• sudo vi /etc/postfix/virtual
  

  info@your-domain-name bob@gmail.com
  everyone@your-domain-name bob@gmail.com jim@gmail.com
  email_processor@your-domain-name curl_email@localhost
  @your-domain-name catchall@whereveryouwant.com
  ted@example.net jane@outlook.com

• sudo postmap /etc/postfix/virtual
• sudo /etc/init.d/postfix reload

You should be able to find your postfix logs at /var/log/mail.log. Good luck!

FreeVote: anonymous Q&A app

I can't believe something like this doesn't exist already! It's far from a polished product, but it's already pretty functional. Feel free to send me feedback, it'll help me prioritize the long list of improvements I've already come up with. This was inspired by my coworkers, every retrospective we all write down answers to sensitive questions "anonymously" on folded papers that one team member gathers and reviews... this way we can do it truly anonymously and all see the results.

FreeVote

C# / OPENSSH RSA ENCRYPTION MADE EVEN EASIER

A long time ago, I posted about importing and exporting Javascript-compatible RSA certificates to and from C#. Last night I realized that I needed a simple and reliable way to shared encrypted code with non-technical folk and decided to put everything I've learned into a comprehensive package called simple-free-encryption-tool that runs on a node.js backend, in your browser, and doesn't even need to be cloned for quick abuse.

This makes strong RSA key generation and encryption and AES encryption simple to implement, and practical to use for client-server communications. It also allows me to give someone an encryption package on a stick (just copy the dist folder) that they can open on any machine.