Building the right thing, building it right, fast

Who I am

My name is Jakub Holy and I’m a software craftsmanship enthusiast and a (mainly JVM-based) developer since ~ 2005, consultant, and occasionally a project manager, working currently with TeliaSonera AS in Norway. More under About and #opinion.

Coding

Guidelines

Commit Message Guidelines

Summarize clearly in one line what the commit is about (preferably less than 50 chars)
Describe the problem the commit solves or the use
case for a new feature. Justify why you chose
the particular solution.
(Preferably 70 chars per line)

Write the summary line and description of what you have done in the imperative mode, that is as if you were commanding someone. Write “fix”, “add”, “change” instead of “fixed”, “added”, “changed”.

The summary must describe both what the patch changes, as well as why the patch might be necessary. It is challenging to be both succinct and descriptive, but that is what a well-written summary should do.

Always leave the second line blank.

Line break the commit message (to make the commit message readable without having to scroll horizontally in gitk, git log etc.).

Try to keep the summary line to 50 chars, though this isn’t a hard limit (The subject line is used all over Git, oftentimes in truncated form if too long. But f.ex. Linux uses ~ 70 chars also for the commit summary line)

Online Resources

Development best practices

Nathan Marz: Principles of Software Engineering, Part 1 – Nathan has worked with Big Data at Twitter and other places and really knows the perils or large, distributed, real-time systems and this post contains plenty of valuable advice for making robust, reliable SW. Main message: “there’s a lot of uncertainty in software engineering“; every SW operates correctly only for a certain range of inputs (including volume, HW it runs on, …) and you never control all of them so there always is an opportunity for failure; you can’t predict what inputs you will encounter in the wild. “[..] while software is deterministic, you can’t treat it as deterministic in any sort of practical sense if you want to build robust software.” “Making software robust is an iterative process: you build and test it as best you can, but inevitably in production you’ll discover new areas of the input space that lead to failure. Like rockets, it’s crucial to have excellent monitoring in place so that these issues can be diagnosed.“. From the content: Sources of uncertainty (bugs, humans, requirements, inputs, ..), Engineering for uncertainty (minimize dependencies, lessen % of cascading failure [JH: -> Hystrix], measure and monitor)

Suffering-oriented programming is certainly also worth reading (summary: do not start with great designs; only start generalizing and creating libs when you have suffered enough from doing things more manually and thus learned the domain; make it possible > make it beautiful > make it fast, repeat)

Kent Beck: Making Making CoffeeScript (screencast, 19min) – an inspiring demonstration of some key development practices: a super-short feedback loop, evolving and refactoring code in small steps without ever breaking it (-> Parallel Change), TDD as a vessel of feadback, without a testing framework.

Web dev

Software Engineering

Seven deadly sins of talking about “types” by Dr Stephen Kell – what goes wrong in many static vs. dynamic typing discussions – worth being aware of before participating: 1. Not distinguishing abstraction from checking, 2. Pretending that syntactic overhead is the issue, 3. Patronising those outside the faith, 4. Presenting type-level programming as a good thing, 5. Fetishising Curry-Howard, 6. Equivocating around “type-safety,” 7. Omitting the inconvenient truths. See also the essay “In Search of Types” attempts to be a dispassionate review of some of the different concepts, purposes and attitudes surrounding the word “type” in programming.
“[..] they [type annotations] force you to structure your code around type-checkability. This is inevitable, since type checking isby definition a specific kind of syntactic reasoning.” “Proof has a cost, and the appropriate expenditure depends on the task.” “Type systems cannot be a one-stop solution for specification and verification. They are limited by definition. They reason only syntactically, and they specify only at the granularity of expressions.”