Comments are not contracts
In Design for Understandability, Jonathan Schuster argues that “[w]e can use ideas like design by contract, class invariants, modularity, and more to create systems that we can understand one piece at a time […]”. Fully agree. However, the author then suggests to implement this using plain text comments in code. That’s baffling:
- We have tools and languages to actually test, enforce or even prove such guarantees.
- Comments are not contracts.
To follow up on the last point, the main example in the article is about this function:
// Implements binary search
int binarySearch(String[] list, String t) {
...
}
That’s the starting point, the “bad” code, which doesn’t provide any guarantees. The “good” code looks like this:
// If the list is sorted, returns the index of the first
// occurence of t in the list, or -1 if not found.
// Behavior is undefined for unsorted lists.
int binarySearch(String[] list, String t) {
...
}
Wat. The only difference is in the plain text informal English language comment, which is often worse than useless:
- It’s imprecise. This is a list of strings, which famously can be sorted in
many different ways1. If the list was sorted in a different locale
from whatever
binarySearchuses, we might get an unexpected result. - It’s misleading. “Undefined” here is meant to be a scary “Don’t do this!”, but the actual behaviour isn’t actually undefined: it will still try to do a binary search! Which is famously . So it will only look at a small fraction of a big list. And if most of the list is sorted the way the function expects (which will happen often, since the collation rules between languages are similar), only some calls will return the wrong result.
- The comment will be ignored by developers and LLMs alike. The developer community knows this.
- The comment and code will drift away from each other over time. This has been true for decades, and we know we can’t just tell everyone to “make sure to keep the comment and code in sync.”
Bottom line: we still need to use tests and other methods to make sure code does what it’s meant to do. And the verification code should be easy enough to understand that the implied contract is obvious. That’s not an easy thing to achieve, but comments are not a good substitute.
-
For example,
sort <<< $'æ\nø\nå'prints different results depending on whetherLC_COLLATE=nb_NO.utf-8orLC_COLLATE=en_US.utf-8. They are both sorted, but according to different sorting rules. Which sorting ruleset doesbinarySearchexpect? Who knows. ↩