If you had to describe how you try to write code in a single acronym, what would it be? I thought a bit about it, and the best I could come up with is CARE. It stands for: Code Aspires to Resemble Explanation. Whichever way I'd explain the purpose of a body of code, I want my code to look like that explanation.
I'm not talking about trying to make lines of code resemble grammatically correct English sentences. It's more about code and (hypothetical) explanation having a similar structure. For example, if your domain is writing utensils and your explanation clearly delineates different behaviors for pencils, ballpoints, and fineliners, do those categories enjoy high-level visibility in your code too? Or will you only come across these categories in the occasional conditional deep down in the implementation?
There's more than one way to explain most things, and so it follows multiple people applying CARE to a problem might end up with very different results. I think that's fine.
Here's some smells that might indicate code could be more CAREful:
- Some terminology appears only in explanation or only in code.
- A single 'beat' in an explanation narrative requires coordination between multiple distinct bits of code.
- The existence of comments explaining what is happening, suggesting the code doesn't explain itself well.