Tom MacWright

tom@macwright.com

Things Learned

This was an earlier, less guarded approach to simple lessons learned building things. Read that post for the refined, older version.

Working Stuff

Programming is mostly mistakes. As you go on, you whittle down the kinds of mistakes you make - fewer syntactical or misuse mistakes - but you’ll never reach zero. Embrace ways to make fewer mistakes but never throw away the tools you have - debuggers, issue trackers, tests - for dealing with them.

Knowing what’s possible is enabling and crippling. This is the classic chessmaster scenario: Kasparov and co. don’t think 50 moves ahead, but they do quickly and efficiently whittle away thoughts that would go on unproductive tangents. Any task is like this: your knowledge of the limits is implied by the choices you make. But this sucks at some point: you get so used to the limits that they become the electric meat: something that used to be dangerous but is now just feared. So people with fresher minds think of solutions you write off as impossible.

Rules of communication: respond on receipt and always summarize. The first I learned in eight grade while freelancing, but the latter is still in-progress. Getting ‘the message’ across is a combination of content and context, and you always have the most context for what you’re doing. How quickly this context-knowledge drops off is a factor of how a team works, how often you talk, and so on. But always assume that people need a lot of background, and a two-sentence summary of what everything means for them.

Tech Stuff

syntastic changed my coding life more than any other tool in 2016: semi-unconscious signals of what’s right and wrong about a file are massive.

Every abstraction breaks eventually. Don’t use a library without checking out its source on GitHub or, even better, cloning it locally. If the library is not absolutely massive, read it for documentation instead of reading documentation: a pathetic minority of technical documentation is useful and current.

Maintaining a library takes twice as much time as maintaining code without a user-facing API. Twice may be an understatement. For instance, maintaing Mapbox.js means indirectly interacting with at least two other people’s codebases every day. The way that libraries is used starts with the simple patterns you expect but expands into advanced uses you’d never think of, or simply suboptimal techniques that are almost impossible to optimize for.

Libraries attract more open-source contributions than user-facing tools. This might go without saying, but it’s very true. Libraries are used by coders who are usually able to understand them and contribute to them. The same is not true of end-user tools: expect a lot of bug reports and feature requests per pull request.