Describe & Declare - Revealing Truth in Code
I've met some people in the church whose primary focus seems to be pointing out sins to avoid. I know I certainly appreciate when people help me avoid problems, like when Vanessa points out a big pothole in the road. But I've noticed something about Jesus. He seemed way more interested in talking about the qualities he wanted people to pursue rather than focusing on the things they needed to avoid. When we focus on being more like Jesus, we naturally avoid sin.
In the last article, I talked about how our code can unintentionally lie (pointing out problems to avoid). In this article, I want to raise our gaze and focus on how to write code that tells the truth. It's a style of programming that is easy to adopt because it boils down to two simple words—describe and declare.
Describe
To give an account in words of something, including all the relevant characteristics.
Descriptive code is concerned with clarity and accuracy. It uses words and concepts that are known and understood across your team. If you're implementing a design pattern, you are using the appropriate terminology, like Factory. If clauses are factored into variables with easy-to-understand names like isJumping.
Descriptive code eliminates ambiguity, identifies "magic numbers," and gives them a name. It values clarity over cleverness and is happy to write a few extra lines if it avoids confusion.
Declare
To reveal one's intentions.
Declarative programming is a whole paradigm in computer science with lots of scholarly articles written on the subject. For our purposes, I'm merely going to define it as writing code in a way that elevates intent. Its highest priority is communicating WHAT you want to happen, not HOW.
Practically speaking, declarations happen at the function level. Take the game of checkers, for example. We could break down the core of the logic into a few easy-to-understand methods.
MovePiece
RemoveJumpedPieces
KingPieceIfApplicable
CheckForWinner
Those methods are pretty easy to follow, even for someone with no programming experience but familiar with the game. The name of each function clearly states what should happen in each block of code.
The interesting side effect of writing code in this manner is that it becomes self-documenting. You don't need comments when your method names clearly state their intent.
This is an important idea; some would even argue that writing code that declares intent is even more important than writing code that works. That might sound ridiculous at first. I mean, isn't it a programmer's entire job to write code that works?
The truth is that programmers make mistakes all the time. Not to mention, the game development process is messy. Jason Schrier describes the process like this, "Making a game is like constructing a building during an earthquake or trying to run a train as someone else is laying down track as you go..." This means that code is regularly in flux, and the problems you're trying to solve keep changing.
In my experience, I've discovered that even if your code doesn't quite hit the mark the first time, any inconsistencies will usually be spotted and corrected over time—if your intentions are known.
