Software Engineering Notes

Martin Jambon, March 2020

Many of these rules are highly counter-intuitive to inexperienced programmers and engineering managers. Use responsibly. 🙂

1 Tell us why we need that code

Rule: When producing a piece of code of any size, make sure it comes with a concise explanation of why it has to exist.

Answers to the following questions must be obvious to a naive reader:


If followed:

If not followed:

2 Don’t break my focus

Rule: It’s fine to interrupt a programmer only for things that don’t require them to focus on something else. For everything else, use asynchronous communication.

Examples: Interrupting someone to ask for their home address is usually ok. Interrupting someone to ask them what they think of a piece of code is not acceptable.

If followed: Programmer gets their job done.

If not followed: 30 minutes are needed to refocus after each interruption.

3 Supervisor could fill in for me

Rule: The programmer’s supervisor, if any, must be able to take over the programmer’s job were they to leave the team.

If followed:

If not followed:

4 Eliminate future tasks

Rule: If the programmer can eliminate future work for themselves or for their peers, they should take the time to do so.

It is important that the manager sees this as well and supports such unscheduled tasks. See also the “No deadlines” rule.

Example: Take a month to create a tool that will eliminate two years of work across the team.

5 No deadlines

Rule: Eliminate deadlines as much as possible.


If followed:

If not followed:

6 Consistent incentives

Rule: Managers must set incentives consistently with best software engineering practices. They must identify and eliminate counter-productive incentives.


7 Zero-effort build

Rule: Any project can be built, tested, and deployed without thinking.

Example: A project is trivially built, tested, and installed with the following commands:

Any deviation from this scheme adds to the cognitive burden of the person who needs to build the project.

8 Routine build under 2 minutes

Rule: A routine make invocation should be short enough for the developer to not lose focus. This is 1 to 2 minutes.

Beyond that, the developer loses focus and starts looking at other things. Prevent that context switch.

If followed: No interruptions. Happiness. Things get done fast.

If not followed: Developer has to wait 5 minutes for their code to compile or pass tests. They go and check their email or company chat. Or maybe they go get coffee or a snack. The 5-min break turns into a 15-min or 30-min break. Employee gets back to their desk and needs to refocus. This adds another 5-10 minutes. In the end, it’s a series 20-min to 40-min breaks interleaved with 10-20 minutes of coding. Nothing gets done fast. Programmer gets sad.

9 Accountability for technical choices

Rule: Let the programmer choose their tools and hold them accountable.

“A good craftsman never blames his tools”

because he gets to choose them!

What if they do:

What if they don’t:

10 Group culture sticks

Rule: Don’t change a culture, replace it.

The culture of a group of people never shifts progressively to a different culture. You can only leave the group, join another group, or start a new group. A culture is defined by a set of behaviors. When these behaviors get in the way of effective software engineering, the group will fail rather than change.

This is why acqui-hires, i.e. the hiring of a successful group of workers, is valuable to large companies. By joining as a group, these workers hopefully keep doing things the way they used to, instead of adopting the unsuccessful practices of the hiring company.

11 Don’t do what you don’t understand

Rule: If you don’t know what it’s for and why it should work, don’t use it. Drop it. This applies to rules, tools, methods, and processes at all levels of an organization.

Of course, this applies to the rules mentioned in this article! Don’t apply them if they’re not justified in your situation.

Justification: Shallow imitation or “cargo cult” comes at a cost: