3 Other engineers and code contracts

Writing and maintaining software is usually a team effort. Companies that create software will typically employ multiple engineers: it could be a team of two working on a single product or thousands of engineers working across hundreds of different products. The exact number doesn’t really matter; the point is that other engineers will end up having to interact with the code we write, and in turn, we will have to interact with the code they write.

Two of the pillars of code quality introduced in chapter 1 were “avoid surprises” and “make code hard to misuse.” These relate to what might happen (and what might go wrong) when other engineers interact with our code. This chapter will discuss different techniques for conveying important details of the code to other engineers (with some techniques being more reliable than others). This will then be formalized with the concept of code contracts and small print. The final two sections of this chapter will go through a worked example of some code that is too open to misuse and misinterpretation and show how to improve the code. Chapters 6 and 7 will provide many more specific examples that build on this chapter.

3.1 Your code and other engineers’ code

3.1.1 Things that are obvious to you are not obvious to others

3.1.2 Other engineers will inadvertently try to break your code

3.1.3 In time, you will forget about your own code

3.2 How will others figure out how to use your code?

3.2.1 Looking at the names of things

3.2.2 Looking at the data types of things

3.2.3 Reading documentation

3.2.4 Asking you in person

3.2.5 Looking at your code

3.3 Code contracts

3.3.1 Small print in contracts

3.3.2 Don’t rely too much on small print

3.4 Checks and assertions