Writing for Developers : Things to keep in mind.

This is in continuation of this post but this time specifically for software developers.
Programmers write all day. Putting some thought into what we write everywhere can make work easy for everyone on the team. 

Writing code – Make it easy to follow

When it comes to writing code you need to write it in a way that reads like a story. It should clarify its meaning on its own.

Developers call it self-documenting code. Code that uses naming conventions and structures to make it easier to understand it. If you are already writing code like this then – Great work! if not, then it’s never late to start.

You might write code only once but then you and quite possibly other developers would read it several times. Think of how many cumulative hours you will save if you write good, readable code today.
There are a bunch of books and blog articles already on this topic. A popular one is The Art of Readable code.

But self-documenting code is not where the story ends,  external documentation is important as well.

Writing external documentation – Help others find what they are looking for 

If you are building a library/SDK that other developers will use, write documentation showcasing usage, provide samples, etc. This will make the life of the developers using your code really easy. It will prevent them from tinkering around with the source code(if available). Ultimately saving them time.

This list on Github contains some really good examples of well-written documentation. Check them out and take inspiration – it contains one of my favorites – Laravel – too.

If you are beginning a new feature write documentation that explains the architecture, design choices, and business use case. This kind of documentation helps with

• Clarifying the approach to yourself and your team members.
• It helps with stakeholder buy-ins. For example, if your product owner understands it, it will greatly aid them to support the development. 

Add architecture diagrams or flow charts to such documents. These are great to give a quick overview. I usually go for https://app.diagrams.net/ which is pretty powerful and free to use. 

Writing on IMs – Think from the receiver’s point of view.

Instant messages are the life and soul of working remotely. As the name suggests you usually expect instant responses. That is only possible if you put in the effort to make it quickly answerable.

Let’s say you are messaging a colleague who had worked on a piece of code. You need some help with it. So instead of writing- “The code is not working for me”, you can instead tell them
1. The problem with some context
2. What you have tried
3. Which part of the code you are looking at
4. Error messages if any

In a nutshell, keep the receiver in mind. Try to make it easy for them to give you a good response. Try to anticipate what are the next possible questions they can ask you and try to answer those beforehand.

Writing on code reviews – Be clear on the expectation

For teams using peer code reviews, it is extremely important that your communication on the PR(Pull Request in Github’s terminology) is exact and to the point.
You should strive to make your expectation and how to improve the code, crystal clear.
It is important because the PR owner might be anxious to merge their code. They might be fixing a bug, or they need to base their next task on it. If your communication isn’t clear and you are not working in the same timezone or are working different shifts in the same timezone. It will further aggravate your situation. Each back and forth can delay the PR. That might mean it can be several hours or even days before we merge the PR. 

To give an example say you are reviewing a code like this:

//...
if (response?.data?.properties) {
  if (response?.data?.properties?.tags) {
    if (response?.data?.properties?.tags?.CostCenter) {
      return response?.data?.properties?.tags?.CostCenter
    }
    return "Others"
  }
} else {
  return "-"
}

So if you say something like “Let’s reduce the nesting here” there is a possibility, they might reduce one nested condition. You might come back with “Let’s reduce it more” leading to a cycle of back and forths. Instead, you can give out the code you are expecting, 

//...
const tags = response?.data?.properties?.tags

if (tags?.CostCenter) {
  return tags.CostCenter
}

if (tags) {
  return "Others"
}

return "-"

 This will help your peer improve. This will also make things go faster as there is no ambiguity and the ask is clear.

There might be more situations where you have to write but you can boil all of it down to one thing. Be empathetic towards your audience.