Communication for devs

Today I would like to write about communication. By communication in a development process I don't necessarily mean verbal communication, but mainly written one.

There are different forms of how a developer can communicate. I will write about three of them in particular. Be it

👉🏽 as a developer of your own open source project, where you need to explain in a README or contribution file what your code or project does and how others can work with it
👉🏽 as a developer in a team, where you have to write Pull Requests about your code that your colleagues need to understand
👉🏽 or just for yourself, e.g. by writing comments in your code, so you don't forget why you used that particular approach at that moment (and also benefit others)

Communication is key as a part of being a developer. If you think about how a relationship works, this is similar, because if you and your partner don't understand each other, there will be no common future for both of you 🙅.

The way of communication leads to a common understanding to achieve a great workflow. You will grow as a team and the quality of your code will increase. It is important to have good communication skills and be respectful to your colleagues in any situation.

💡 To get the most out of this post, you should also understand the concept of a Git workflow and what a README and Pull Requests are.

Communication is key

You may know the feeling when you read a documentation of a project or tools and don't quite understand what it's about or how to use that particular feature, and wonder why the creator wasn't able to write the documentation in a way that everyone understands. But for you as the creator, it often feels like, "Yes, people will understand," because it's clear to you.

However, we want others to understand as well as possible what we're trying to accomplish with this code or project - to avoid the back-and-forth that comes from not explaining things as well as we can, and we also want to avoid confusion that comes from not being as clear as we could be at the beginning.

To achieve this, it is important to write good documentation that everyone can understand. Write it as simple as possible to make it as accessible as possible.

Documentation

There are different forms of documentation. If you want to use a new tool or library, such as React, you should read the official documentation, which should help you understand how React works and how to use and implement it in your project. Currently, these documents are the beta version still in progress, but they promise to be better set up than their previous ones were.

Another form would be if you want to contribute to an open source project and want to find out how best to contribute, what is expected, or how best to do local setup. Good documentation that explains these things in detail is key to a successful contribution. Take a look at EddieHub's contribution file for their LinkFree project, and how detailed it is.

A README file is a must for every project on GitHub. It should contain information about the project itself, what it is about, include screenshots showing parts of the project or code while explaining some approaches. It should also explain how a user can set up your project locally and how to run it, as well as what dependencies and languages are used. To learn more about how to write a README, check out this article.

Good documentation can help not only the user, but also ourselves to figure out where we really stand when it comes to learning how to do certain things in code. Once we learn something, we probably won't be able to remember the exact steps, especially if we don't really know it at first and try a lot to see if something works or not. So not only can it help you figure out where you stand, but it can also help you learn by figuring things out and writing them down and thinking about them.

It's also a great tool for thinking through big decisions. If we don't know exactly what steps we need to take to achieve a certain outcome or task, we can often go back and rethink whether we want to do the same process for that task or maybe follow a different approach.

Pull Requests

The purpose of a Pull Request (short PR) is to give your reviewers context about your code before it is incorporated into a larger part of the project or application as a whole. This is an opportunity to explain why you made certain decisions and made certain tradeoffs as a contribution to others.

If you want to give a little more context to what you are explaining, you can link to a more detailed description of the issue we worked with. 🔗 This is a nice experience for your code reviewers if you have more to say, which can be supported by letting them decide if they want to follow the link or not.

✅ It's important to check ourselves before we ask others to review. Ask yourself if my recent changes are acceptable, what questions might I have. Sometimes we are just happy to have finally finished the code and want to complete the PR as soon as possible, but doing this extra step before asking others for a review makes the communication between the reviewer and ourselves more efficient.

This prevents the reviewer from telling me to change something that I would have seen myself if I had reviewed it before sending the PR. It saves bad vibes that could be generated as well as time between updating the code and merging the code.

A PR contains all the changes you made and pushed to the branch with a commit message. Make sure that your commit messages are meaningful. To learn more about how to write a Pull Request and commit messages, check out this article.

If you are in the position of testing other people's code, it is important that you describe your comments objectively. You can add some links to specific topics that the developer can read more about to understand why your suggestions are the better option at this point.

Comments in the code

Leaving comments in your code is very helpful, especially if you are on a team that will be reviewing your work, because it gives your team context as they go through your code.

Code can sometimes be self-explanatory, but the decisions behind the code are not always self-explanatory. There are many approaches to achieving the desired result. And maybe the very first decision interferes with another part of the code, so you decide to take a different approach.

What direction did you take in your code, what were you thinking? The comments reinforce the approach and help understand why you decided to write the code the way you did.

Because it's not about the how, it's about the why, because your team members will know what that particular code does when they read it. If you leave a comment, everyone can also understand why you chose that code and what approaches you took. Comments can provide additional explanations that emphasize your decisions.

/* Remove all animations, transitions and smooth scroll for
 people that prefer not to see them */

@media (prefers-reduced-motion: reduce) {
  html:focus-within {
   scroll-behavior: auto;
  }

Conclusion

Good communication in any form is key to being a good developer. It's not only a great tool for us personally when we're documenting, but also for a team environment, for example, if you have a new role and there's not necessarily good documentation when it comes to on-boarding new members. It can be very useful to have that kind of basic documentation, like "This is the process we follow", so there's no confusion about what comes next.

❌ Avoid institutional knowledge, which is things that you know, or if you work in a company or are involved in a community, and that your teammates know because some things have always been done that way, or you have more experience, but it's not written down somewhere so it's not necessarily accessible to new people coming onto a new team.

So if the documentation is available to a new team member or contributor, it avoids the gap between those who have been around a long time and know how things work, and those who are brand new and are just learning the ropes. And that empowers all team members 🫂.

Now that you've learned about communication as a developer, take a look at how a Git workflow can look in detail (my latest experience) and how to create good Pull Requests and a README file.

Thanks for your reading and time. I really appreciate it!