1 Other engineers and code contracts

 

Chapter 3 from Good Code, Bad Code by Tom Long

This chapter covers

  • How other engineers will interact with our code
  • Code contracts and small print in code contracts
  • How minimizing small print can help prevent misuse and surprises
  • If we can’t avoid small print, how checks and assertions can be used to enforce it

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.

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

3.4.1 Checks

3.4.2 Assertions

Summary