CodeNewbie Community

Unpublished Post. This URL is public but secret, so share at your own discretion.

DRAFT: Communication for devs

This blog post is about communication during development process because it is important to have strong communication skills as well as always being respectful to your colleagues in any kind of situation.

To get the most out of this post, it’s best if you understand that communication within a developer team does not necessarily mean spoken communication but especially written one. You might also want to understand the concept of a git workflow (Link to another post).

Communication for devs is an important topic because when working within a dev team it is key to understand each others position, that others are able to understand your code and you are able to understand others as well. You’ll most likely use this when creating pull requests, or writing comments in your code.

This concept is like key as part of being a developer. If you think about how a relationship works, this is similar because if you and your partner do not understand each other, there will be no future for both of you together. The way of communication causes shared understanding in order to achieve a great workflow.


Every company or project has its own workflow. Usually, you work on your own branch first and write comments in your code so that future developers who have never worked on the project before can easily understand what is going on. It's important to note why you chose a particular way to write that piece of code when the other way might not work.

Next, move into the main branch by creating a pull request to have your code reviewed. It is important to describe in detail the task you worked on, what was expected, what and how you accomplished it, and write a description for the tester on how to test your code.

If you are in a position to test 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.
(More on Git Workflow Link)

Let's get into detail

You may know the feeling when you read documentation 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 could understand. But for you as the creator, it often feels like, "Yeah, people will get it," because it's clear to you.

We want others to understand what we're trying to do and accomplish as effectively as possible. So we avoid the back-and-forth that comes from not explaining things as well as we can, and we also avoid a lot of confusion that comes from not being as clear as we could be at the beginning.


There are different forms of documentation. If you want to use a new tool or library, say React, you should read the documentation (link to React docs) which should help you understand how React works and how to use and implement it in your project.

Another form would be if you want to contribute to an open source project and find out how best to contribute, what is expected, or how best to get local setup. Good documentation that explains these things in detail is key to a successful contribution. (Link to a good OS doc).

Good documentation can also help ourselves figure out where we really stand when it comes to learning how to do some things in code. Chances are that once we learn something, we won't be able to remember the exact steps, especially if we don't really know it at first and do a lot of trial and error to see if things work or not.

So it can help not only with figuring out where you are, but also with learning by figuring things out and writing them down, and kind of thinking about it. It's also a great tool for thinking through big decisions.

A lot of times when we're not clear on exactly what steps we need to take to achieve a certain outcome or task, we can go back and rethink it in terms of whether we want to do the same process for that other task or find a different way and work with teammates that way.

Add a file to your projects where you explain in detail on how to use your project, the code and what exactly the code does.

Pull Requests

The purpose of a pull request 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.

Here are some examples that can really help write an outstanding PR by showing screenshots or videos of what the code does on the UI. Link to resources and permalinks to code you reference outside of the PR so you can not only share how a code works, but link to it as well.

If we need a little more context to what she's explaining, we can call out the link with a more detailed description of that particular topic she's working with. This is a nice experience for your code reviewer if you have more to say, which can be supported by letting them decide if they want to follow the link or not.

Finally, 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 get the PR done as quickly as possible, but taking that extra step before asking others to review it speeds up the efficiency of communication between the reviewer and yourself.

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 a little extra time between updating the code and merging the code.

Comments in your code

Leaving comments in your code is very helpful, especially if you're on a team that will be reviewing your work, because it gives your team context as they go through your code. In the same way that we can self-document our process, it adds an extra layer when we're actually doing it and thinking about doing it at the same time.

When you leave comments in the code, it helps teammates do the same thing while they're reading the code and kind of processing what that code is supposed to do. What direction you took in your code, what you were thinking?

The comments reinforce that, help them think about it, and give them an additional explanation for why you decided to write the code the way you did.

Code can sometimes be self-documenting, but the decisions behind the code are not always self-explanatory, that's the same as software development where there are just an infinite number of trade-offs, it would be great to write it that way, but maybe that code doesn't work when you make a change, so we choose a different path.

If you leave a comment in the code, everyone can understand why you chose that code and what you were thinking. In terms of HOW, the focus should be more on the WHY of the code, because your team members will know what it does when they read it. And so those comments in your code can give that extra explanation that underscores why you chose that code.



Good communication in any form is key of being a good developer. Not only is it a great tool to use for us personally when we're documenting, but it's also great 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 foundational documentation, such as "This is the process we follow" so there's no confusion about what comes next.

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

So when the documentation is available to a new team member, it avoids that disconnect between people who have been on the job for a long time and just know how things work and people who are brand new and are figuring things out as they go. And that empowers all the team members.

Now that you’ve learned about communication and git workflow, take a look at how to create PRs and write comments in your code.

For more reading, checkout official GitHub docs, my account, and my twitter account.

Discussion (0)