HackMake

Hacking Better

January 29, 2015

A couple years ago (see: archives) I was very much in to finding or writing hacks to help smooth out the little bumps when software wouldn’t quite work the way I wanted it to. Some of these hacks were quick, inelegant fixes just to satisfy my itch of trying to solve a problem in a different way and some were bigger projects that I thought might get a decent amount of use over time. With that passage of time, different jobs, and work styles, only some are still in use while many of those hacks have become irrelevant, abandoned, and forgotten.

I’ve learned a few things while <airquotes>hacking on my workflow</airquotes> that I’ve only recently became cognizant of:

  • It you want your “hacks” to be functional for a long time, don’t do much funky stuff
    • The problem here is that if you’re new, you don’t know what’s funky and what isn’t
    • Funky stuff includes (but is not limited to):
      • Referencing outside dependencies which aren’t controlled; links break or files move and your script fails
      • That clever solution you thought of which was just too clever (clever = complex; complexity = evil)
  • See if other people have built it (and done a better job)
    • I heard a saying once: “A new engineer thinks, ‘Hey, I could build that’ while an experienced engineer thinks, ’I bet someone else has built that”
    • Building might be fun but maintaining isn’t, so leave that to other people as much as you can
  • Document what you’re doing
    • The path to how you solved this problem is really important and will prove valuable in the future (probably more valuable than the script you’re writing)
    • The links, StackOverflow posts, and mailing list archives that helped you solve this will help you again next time, or when this breaks
  • Document what you’ve done
    • Not for others but for your future self
    • Documentation doesn’t always need to be inline because you should be writing readable code
    • Keep a wiki of what scripts you have, where they’re expected to live, what other scripts might reference or execute them
      • I easily finished the below script when I found an old one that I had totally forgotten about that did a similar thing
      • If I would have had a scripts database to search through (like I do now) I would have solved this problem a lot easier
    • Equal parts writing code as writing documentation; if you’re spending 5 minutes thinking, you can spend 5 minutes writing about what you were thinking. You don’t get that time thinking back but you can keep that knowledge if you write it down
      • There’s a good chance that you’ll never use this hacky script again but you’ll probably use this knowledge again, so actually learn something for good by writing it down
    • The good developers I know document everything
  • Build in checks to see if everything is working as planned
    • I’ve spent enough time writing scripts, testing them out, and then loading them in to Lingon only to have them fail in the next day or two after I’ve forgotten about them
    • I don’t check back and this backup script script hasn’t ran in 6 weeks
    • I’ll be honest that I don’t know a good way to programmatically check that something hasn’t happened but it’s a good thing to think about and build in to your scripts if you’re smarter than I am

Here’s a good example of not doing funky stuff.

I was writing this script today that I’ve wanted for a while but just haven’t sat down to do. It would take the first line of a text file in BBEdit, make it in to a URL-friendly slug, and save the current text file with that slug as the filename. I’ll use this for every blog post I write (which doesn’t happen so frequently anymore).

At first I had this:

set title_slug to do shell script "echo " & quoted form of title_text & " | ~/Dropbox/bin/sluggify.rb"

where I reference an external script (sluggify.rb) which takes “A Title Like ‘This’” and does some gsub foo on it and turns it into “a-title-like-this”. What happens if, say down the road, I stop using Dropbox to sync and take my belongings to some other cloud? This script breaks because it can’t find ~/Dropbox/bin/sluggify.rb and I have to go fix it. Instead, I can do something kind of less funky like this:

set title_slug to do shell script 
        "ruby -e \"input = "
            & quoted form of title_text
            & "print input.gsub(/[ [:punct:]]+/,'-').gsub(/(^-|-$)/,'').downcase\""

where I take that ruby code and execute it inline. Less external dependancies, less funky stuff. Here’s the full script, by the way (because I like you):

set user to system attribute "USER"
set drafts_folder to "/Users/" & user & "/Dropbox/hackmake/drafts/"
set ext to ".md"

tell application "BBEdit"
    tell text window 1
        set title_text to contents of line 1
        set title_slug to do shell script 
            "ruby -e \"input = "
                & quoted form of title_text
                & "print input.gsub(/[ [:punct:]]+/,'-').gsub(/(^-|-$)/,'').downcase\""
        set draft_path to drafts_folder & title_slug & ext
    end tell
    save document 1 to draft_path
end tell
You’re not what you make–You’re the problems you solve.
–Internet Contrarian, Sean Korzdorfer in An Annotated Life

I’ve been drifting back and forth in the last year about how important “they way we work” is. Is Microsoft Word enough? Or do we need to find a fancy way to do something as to satisfy our feeling of being a special snowflake artist-type? I used to put more value in the things I make but, over time, I’m realizing that a lot of those things just whither away or are never paid attention to in the first place. That doesn’t mean stop making but I think I’m putting more energy in to reflecting and trying to understand the process that got me to the end of a project–that’s what makes me better at what I do.

The problems I solve and the things I learn along the way are a much better indicator for me of “working better” than what’s in my toolkit. I focused a lot on capturing what I needed to do but not capturing what I had done and learned. With this post-productivity mindset, I’m focused more on what I’ve learned not what I’m doing and that helps me hack better and work smarter.