# Code Only Says What it Does

DevFeed: [Code Only Says What it Does](<https://devfeed.tech/articles/code-only-says-what-it-does-12496.md>)

Original publisher: [Read original article](<http://brooker.co.za/blog/2020/06/23/code.html>)

Author: Marc Brooker

Published: 2020-06-23T00:00:00Z

Content type: opinion

Language: en

Sources: [Marc Brooker's Blog](<https://devfeed.tech/sources/marc-brooker-s-blog.md>), [Marc Brooker's Blog](<https://devfeed.tech/sources/marc-brooker-s-blog-2.md>)

Topics: [Code](<https://devfeed.tech/topics/code.md>), [debug](<https://devfeed.tech/topics/debug.md>), [distributed-systems](<https://devfeed.tech/topics/distributed-systems.md>), [systems](<https://devfeed.tech/topics/systems.md>)

Tags: [code](<https://devfeed.tech/tags/code.md>), [debug](<https://devfeed.tech/tags/debug.md>), [debugging](<https://devfeed.tech/tags/debugging.md>), [distributed-systems](<https://devfeed.tech/tags/distributed-systems.md>), [documentation](<https://devfeed.tech/tags/documentation.md>), [java](<https://devfeed.tech/tags/java.md>)

## AI overview

The article argues that code describes what a program does, but usually does not capture what it should do. This makes debugging and maintenance difficult, especially in distributed-system protocols and business logic, where implementation details can obscure intent. It discusses using formal models, design work, and documentation to resolve ambiguities and preserve intent.

## Source excerpt

Code Only Says What it Does Only loosely related to what it should do. Code says what it does. That's important for the computer, because code is the way that we ask the computer to do something. It's OK for humans, as long as we never have to modify or debug the code. As soon as we do, we have a problem. Fundamentally, debugging is an exercise in changing what a program does to match what it should do. It requires us to know what a program should do, which isn't captured in the code. Sometimes that's easy: What it does is crash, what it should do is not crash. Outside those trivial cases, discovering intent is harder. Debugging when should do is subtle, such as when building distributed systems protocols, is especially difficult. In our Millions of Tiny Databases paper, we say: Our code reviews, simworld tests, and design meetings frequently referred back to the TLA+ models of our protocols to resolve ambiguities in Java code or written communication. The problem is that the implementation (in Physalia's case the Java code) is both an imperfect implementation of the protocol, and an overly-specific implementation of the protocol. It's overly-specific because it needs to be fully specified. Computers demand that, and no less, while the protocol itself has some leeway and wiggle room. It's also overly-specific because it has to address things like low-level performance concerns that the specification can't be bothered with. Are those values in an ArrayList because order is actually important, or because O(1) random seeks are important, or some other reason? Was it just the easiest thing to write? What happens when I change it? Business logic code, while lacking the cachet of distributed protocols, have even more of these kinds of problems. Code both over-specifies the business logic, and specifies it inaccurately. I was prompted to write this by a tweet from @mcclure111 where she hits the nail on the head: Since most software doesn't have a formal spec, most software