Developers love writing code because they get to invent things. But someone else has to use the code, operate it and even pay for it.
When I order a dish in a restaurant, I expect the chef to prepare what I order - and to make it more delicious than I could have done myself. Even if I asked for vegetarian and the chef prefers a bloody steak and hates salad, I would not be content with a few slices of cucumber, just because they were the remains from preparing the burgers. I imagine that the chef takes pride in her work and is affirmed when her product satisfies customers.
We as software developers like our jobs too. So let’s make an effort to satisfy the people we interact with during development. When we are given a task, when turning it into code, and when putting the software into the hands of users.
Understand the task
When you are handed a task, make sure it is described so you know what you have to do. There must be a definition of done. How do we know if it is working? Who is the recipient of the work? What will an end user be doing? What indicates whether the task is done right?
You may expect your product owner to have groomed the task in sufficient detail before handing it to you. But if they haven’t, for some reason, raise the questions that you need answered.
Imagine that you are the end user facing the software for the first time. You expect things to just work and you definitely aren’t going to read any instructions. So throw away your assumptions. Don’t be a technical apologist.
Build the product right
When you throw yourself at coding a new project, take a moment to orientate yourself in the code base. Where will the code go? Figure out what the existing code does by running associated tests and reading the code. Plan how your user story can be described as unit tests.
Sometimes we feel we don’t have time to care about clean code just for this task.
But then try to imagine: How would you like to come back to this piece of code in six months from now?
Would it be clear to read? Would you be able to test that some new changes did not break anything?
Take care to not leave legacy code behind.
Collaborate when you deliver
Look at your diff before you create a review request, because at that point you are asking someone else to spend time looking at it.
Write a meaningful commit message.
Reviewers are not psychic. They do not know what you thought about when you designed the solution or wrote the code.
Put yourself in their shoes: How would you like to review your code with that commit message, that structure of code and that kind of tests? Would you be able to understand it?
Understand how the code will run
Think about the stack on which your code will run. Are you able to run your code change in a production-like environment? Imagine the people who will operate your code. What if a service fails to start, but doesn’t provide a meaningful error message? Consider how much configuration is needed before the code can run. Does an operator need to follow a long list of instructions?
Consider whether log files are easy to find. Try reading the log messages after running the code to see if they are useful. The log should provide error details when something fails, but on the other hand shouldn’t be filled with stack traces just because of user errors.
Consider how the code can be monitored. Should your application expose custom metrics to collect data about usage, resources or events?
You may encounter problems implementing a story as it was specified. It may be after most of the estimate is already spent. Be open and make it visible on the daily standup. It may or may not be your fault. Product owners will appreciate fast feedback and will rather adjust expectations than have grumpy users. QA engineers will appreciate a functional but limited setup, over stumbling upon bugs you tried to hide. Operations will appreciate knowing a performance limit, because it means you have given it some thought.
Are you imagining things?
How can we possibly achieve this, when we are so busy? There is always a pile of work waiting for us. To see why it is worth it, rephrase that last sentence: There will always be that pile of work, even if you code as fast as you can, skip writing tests and don’t talk to anyone. By making an effort, you actually end up saving time. Everything you clarify about the world around the code leads to better code. You may save time otherwise spent on a bugfix, supporting a user or trying to understand your own code six months later.
Put yourself in the shoes of the people you collaborate with. What do they expect?