your-problem.md

##What's Your Problem?

Abstract

You're 3 nested conditionals deep in a 50 line procedure wondering what you did to deserve this incomprehensible codebase. BDD, TDD, OOP, FP, and all the other letters of the alphabet won't help, at least not on their own. Before better coding practices must come the question: "What is the problem we're solving?

This talk makes the case that it is impossible to do our jobs as software creators without first fully grasping the problem being solved. We'll then discuss practical ways to discover the problem statement when all we have to work with is a feature request.

Outline

1 - Why

• Uses a language that's precise enough for a machine to use.
• Consists of sets of instructions, or steps to be performed, encoded in that language
• When the language was designed to allow for conditional jumps in the instructions, then we call it a programming language. Ruby, Java, Clojure,
• When the language does not allow for those conditional jumps, or only allows them through accident, then they are not a programming language. Regular expressions, HTML, XML, JSON, ANSI SQL, CSS.
• When I say 'programming language' or 'programming' in this talk then I'll often mean 'a precise language that is parseable by both humans and machines.'
• We're paid to program, so we're often paid to encode steps needed by people other than us. We're probably not scratching our own itch by default.
• When I say 'encode steps needed by other people,' that is a stand in for stories, use cases, requirements, cards, or features. I use the terms interchangeably.
• Programmers cannot encode steps needed by other people unless they know what steps need to be encoded.
• Our solution in IT is to have somebody (often not a developer) break stories down into small, precise, natural language instructions for developers to then encode in a programming language.
• Asking a developer to encode steps that they do not understand is like asking a writer to draft a screenplay about a topic that they have no familiarity with.
• What would it look like if that's how writers worked? We don't have to wonder
• bad tech in movies (https://www.youtube.com/watch?v=QmvL7fgp7TM#t=102)
• What happens when writers familiarize themselves with tech before writing about it?
• good tech (kill -9 in Tron Legacy, Nmap in Matrix Reloaded)
• Whenever developers fail to understand the steps being encoded (learning the domain) then they are remaking the movie Swordfish. That movie does not need to be remade.
• The solutions we present are often a mis-match for the solutions needed. They don't solve a problem that anybody actually has.
• We guard against problems that aren't actually problems. Look at any test suite for evidence.
• It's harder to build meaningful abstractions when we do not understand the real-world analog. A developer who understands the domain might be able to take 2-3 stories, combine them, and ship an effective abstraction. I argue that a developer who does not understand the domain is unable to do the same.

2 - How

• When talking with humans, ask questions when you do not understand.
• Keep asking questions until you understand. This will be hard, and embarrassing. You may have to find more people to ask. They may not be in IT.
• Developers tend to be far more comfortable shipping software that solves no problems than they are asking a question of somebody who is outside of their chain of command.
• Examine if you're OK with this.
• Questions can be seen as a challenge and they may be embarrassing when the person you're asking feels that they should know the answer but doesn't. A potential solution is to use private conversations with trusted peers to build support for getting answers.
• When talking with the computer, ask questions when you do not understand.
• Keep asking questions until you do understand.
• Do you know what problem you're trying to solve right this second?
• Really?
• Are you sure?
• Is there any chance the person you got your understanding from had an incomplete picture?
• How does the person paying you to write code feel about the problem you're solving right now?
• The users?
• Are they the same, and if not, do they feel differently about the importance of the problem you're trying to solve?
• When code is confusing
• Is the code confusing because it's poorly written, or is it confusing because the person who wrote it is confused about the problem space?
• Some programming problems are chores - writing to the DB, serving web pages, making a REST API call. When looking at the code, are the chores mixed up with the problem being solved?
• Are you being asked to solve two mutually exclusive problems? Is that a sign that product owners don't fully understand the problem space, or a sign that multiple people are requesting solutions and they're not talking.
• Are you being asked to solve multiple problems, while not technically mutually exclusive, might as well be with the given resources. In other words, if implemented as asked the project would cost an order of magnitude more to complete. (This scenario is far more common.)

Not sure if my feedback is still valuable at this late hour. However...

To quote a brilliant man: "Are you able to tell me the focus of your idea in 2 or 3 sentences?"

If I had to take a stab, I'd go with: "The first step to writing clean code, is to develop a solid understanding of the problem domain. If you don't understand the problem you're working on, here's how to fix that."

The bits about difference between types of languages seems superfluous except for to point out that programming languages are necessarily more precise than the natural languages we gather requirements in. I think this is an apt point to insert an office space gif:

I feel like the How section can be boiled down to "Ask questions when you don't understand something. Is there any chance that you don't have a complete picture of the problem space? If you think you understand something, constantly question that understanding. If you feel uncomfortable with this, get over it."

"Is the code confusing because it's poorly written, or is it confusing because the person who wrote it is confused about the problem space?"

keep in mind these are not mutually exclusive states. At the same time, when approached by someone with knowledge of the problem space and good code design skills, the two solutions may be indistinguishable. Are there any ways we can help identify the difference between these two situations?

Are there counter arguments to this? Examples of good, clean code produced without complete domain knowledge? Techniques for producing good code while lacking a complete understanding?

"Some programming problems are chores - writing to the DB, serving web pages, making a REST API call. When looking at the code, are the chores mixed up with the problem being solved?"

I feel like this is orthogonal to the problem statement. However, I think it would be good to tangentially bring up that these chore can possibly be completed separately and without full knowledge of the domain. Perhaps this is the start of a technique. Separating the crunchy external dependency cruft from the creamy, nougaty business logic is a good pattern to start with regardless of your knowledge of the problem domain.

"How does the person paying you to write code feel about the problem you're solving right now?
The users?
Are you being asked to solve two mutually exclusive problems? Is that a sign that product owners don't fully understand the problem space, or a sign that multiple people are requesting solutions and they're not talking.
Are you being asked to solve multiple problems, while not technically mutually exclusive, might as well be with the given resources. In other words, if implemented as asked the project would cost an order of magnitude more to complete. (This scenario is far more common.)"

These are good points to go under a heading of "How to tell if the business person you're dealing with is full of shit"

"When talking with the computer, ask questions when you do not understand."

Not sure where you're going with this. Perhaps drawing a parallel between continuing to ask people questions and how you might prod at an API trying to figure out what it's doing.

Much appreciated Dusty. Not too late at all.