DEV Community: Adriano Martins

Why Developers Should Care About Knowledge Sharing

Adriano Martins — Mon, 18 Oct 2021 09:18:44 +0000

Sharing knowledge usually comes as the last step of a process, or even worse, as something optional, that can be passed on if need be. This makes it easy to skip on this step if you feel you’re tired, or your team is busy. Developers are almost always creating new technologies and figuring out new solutions. Odds are, whatever knowledge you acquire won’t be available anywhere else. The time has come to remind everyone of the fundamental benefits of making whatever knowledge you’ve acquired available to your colleagues.

Why it helps you

Knowledge sharing is the second biggest problem software companies face. It affects everyone, so it also affects anyone. With the advent of remote work, this issue may become even more important. First of all, let’s appeal to our own self-interest. Sharing knowledge doesn’t only help our team, it actually helps those who are imparting the knowledge in more ways than one.

Let’s see:

You are advancing your own knowledge. By explaining what you’ve learnt to someone else, you are consolidating what you’ve learnt. You will retain it better, systematise it better, and, frankly, you’ll probably advance it by seeing it through others’ eyes. You will have to consider what you’re sharing and think twice about it. That reflection will bring with it valuable learning.
You will be receiving feedback. No developer is an island. We learn from others. By sharing what you’ve learnt, you will be receiving other people’s thoughts on the subject, which will surely advance your own understanding. Maybe they will even correct some aspect of it that you misunderstood.
You will help future you. If you learn something and just file it away in the caverns of a closed pull request, odds are you may not remember it fully whenever you bump into the same problem again. If you write it down, though, and teach it to others, it will be right there for you when you need it. It’s the easiest way to only solve problems once.
You will be advancing your career. Sharing knowledge and contributing to the team’s success does not go unnoticed. If when people are in trouble and seek solutions your name pops up all the time, everyone will take notice. This is how promotions happen.

Why it helps your team

But sharing isn’t just about oneself, now is it? There must be advantages for the whole team. Let’s see what they are.

It helps build team spirit. This may sound like a meaningless phrase, but it isn’t. What goes around comes around, and a team that is accustomed to helping each other will resort to helping each other naturally. Giving everyone a hand shouldn’t be contingent on someone being in trouble.
You will be saving everyone A LOT of time. How long did it take you to solve the problem? An hour? Two? A whole day? Whenever someone on your team runs into the exact same issue, they will (depending on skill level or just sheer instinct) take roughly the same amount of time. If there’s an explanation available, though, that everyone has knowledge of… Not so much.
You will be building a knowledge base. It may seem like just a small addition, but small additions build up. If your team develops a culture of sharing knowledge, they will inevitably create a repository that will become a cornerstone of success.

How to do it

So, are there any best practices, aside from simply gathering the team and telling them, or writing stuff down somewhere public, such as an internal Wiki?

We do have some ideas:

If you’re using Reviewpad, which you should, the Comments from the Past feature makes it so whenever someone touches code with comments, they’ll be able to see what was shared when that code was made. Forget about re-working the same problems, or going down avenues that somebody else already found out that don’t work.
Whenever a team member explains something to you, encourage them to document it. If it was useful to you, it will likely be useful to others.
Much in the same way, whenever someone asks you for help, document it.
Whenever you are the one who needs an explanation, avoid asking in private. Ask on a public forum, so everyone can read the discussion and take advantage of it.
Make it easily accessible. Your knowledge base needs to be freely and easily accessible to everyone, at all times. Developers don’t particularly like over complicated wikis, so it’s up to you to create this space.

One of the reasons why we are building Reviewpad is making knowledge sharing easier and more convenient to everyone involved.

Reviewpad is about communication as much as it is about reviews.

Are you ready to give it a go?

Pull Requests for Dummies

Adriano Martins — Mon, 30 Aug 2021 09:48:50 +0000

Debate about code reviews is often dominated by debate about pull requests. The confusion between the two is so common we have made it a point to clarify that they are not the same quite often. So what are pull requests? And why are they called that way?

Imagine you're writing a book.

(You knew that was coming.)

In this case, you're writing collaboratively. Let's say it's a non-fiction book, or a technical manual. Something that requires a certain degree of responsibility and accuracy.

You will need to figure out a strategy to make sure there are as few mistakes as possible.

How about… version control?

If this is a collaborative work, then it stands to reason that you will want to keep your file (let's say a Word document) somewhere everyone can easily find it and work on it. Let's say you keep your manuscript on Dropbox.

You (or any one of the other authors) are working on a specific chapter, so you download the manuscript that the team is keeping online. You would never edit the manuscript directly, that would be way too risky. You create a temporary version, and label it as such.

You do your work, write your lines, make sure everything is to your liking, and then what do you do?

You upload it to the Dropbox, always making sure that it's labeled correctly as a temporary version. Why? Because you would like feedback from your colleagues before pulling everything together (notice our word choice there 🧐).

What's a simple word for asking for feedback?

A review.

Dictionaries are interesting.

Anyway, your colleagues will then look at your brand new text and they will carefully look over it. They will correct mistakes, leave notes and suggestions, make recommendations, and, of course, if all is well, simply accept it.

When this is done, and the author of the new chapter is confident he's answered all the queries and fixed all the problems, they can then request whoever is responsible for the manuscript to pull his changed text into the main document.

And that is what a pull request is.

When a developer finishes a task, they will start a process to join the new code to the project. For that purpose, they will ask whoever's in charge of the project to pull the changes from their working branch to the main branch. Voilá, a request to pull changes: a pull-request.

So it's not a review, but it implies a review?

Most of the time, yes.

Unless the changes are very trivial, it would be irresponsible to pull changes into the main branch without performing a code review.

What happens frequently is the opposite: code reviews happen all the time without the need for a pull request.

A developer might want to review the changes between different states of a project for many different purposes:

Auditing the source code is always important;
Reviewing code without making it visible to everyone else in the project (pull-requests are always visible), for whatever reason;
Reviewing the code when the project is scattered across many repositories;
There are even some software development methodologies that don't use pull requests at all! And they still review code.

We hope this helped clear up what pull requests are, and why they are often wrongly mistaken for code reviews. Are there any topics you'd like us to cover next on this series?

If so, you know where to find us on Twitter (@reviewpad)!

Git For Dummies

Adriano Martins — Thu, 01 Jul 2021 16:27:24 +0000

We started this series with a quick introduction to code reviews, and now we are extending the analogy and applying it to one of the most important tools of our trade: Git. It’s a revolutionary technology that entirely changed the field when it came to be in 2005, and we are going to explain how it works.

Think of a book.

How many authors does a book have? One, you say? Not necessarily. Every kind of book, from fiction to non-fiction, from serious journalistic inquiries to the most commercial of novels, can have several authors.

Let us tell you how collaborating on a book usually happens, and you will understand how Git works.

1. You are writing as a team

Let’s say you are writing a book and you have a co-author. Now, in the before-times, when the Internet wasn’t a key part of everything we do, you would probably write down your bit, they would write down theirs, and you would need to either meet physically or exchange documents somehow (mail, a delivery man, etc.) to be able to compare and contrast versions.

This has a number of problems.

You can’t work on the same section at the same time, for one. If you want to both work on the same section, one of the writers will have to combine the different documents.

What happens if an author wants to make a change to a chapter that is already written? What happens if an author makes a lot of changes, and the others dislike it and want to go back to the old text?

Writing code as a team had many of the same challenges before Git came along. Git is a VCS, or Version Control System.

2. A good VCS changes everything

Contemporary writers have Dropbox, Google Docs, and other tools that allow for synchronous work. No one really exchanges paper manuscripts anymore because computers and the Internet make life significantly easier.

These tools use one form or another of a VCS much like Git.

If a team of writers is writing their manuscript on, say, Google Docs, they can do a number of things that were impossible in the past, such as:

All writers can collaborate on the same document at the same time;
The main version of the book will always be up-to-date, regardless of changes;
Past versions can be accessed easily;

There are plenty of VCSs out there that facilitate development, but Git is definitely the most popular, and it allows developers to do all of these exact same things. The most popular Code Hosting companies using Git are GitHub, GitLab, and BitBucket. Yes, Git and GitHub are not the same thing.

3. Keeping track of every line written

When you’re an author working on a book, you are going to take great care with the wording and every choice made. This is every bit as true even if you have co-authors.

This is why modern VCSs such as Google Docs (which is more than a little bit inspired by VCSs) have a number of features that allow you to keep track of what’s happening while you and everyone else works.

You can, for instance:

Download and upload up-to-date versions of the book;
Create alternate/temporary versions of the book which you can share with the other authors;
Join temporary versions with the main one;
Easily deal with new chapters added while other writers worked on other parts of the book;
Go back to older versions in case something was deleted or lost;

But what if a writer particularly likes or dislikes a specific line, section, or chapter, and wants to know who wrote it?

You can do that too.

When VCSs came up with the ability to identify the author of every single line of code, this changed things. Now it’s normal.

Most of the things we’ve listed are taken for granted. They seem like the basic features of any online text editor. Every single one of these features was introduced or made mainstream by Git, though, and every single one was hailed as the key innovation they truly were.

So now, as a way to break this little analogy we’ve built, here’s some Git terminology and what it compares to:

Writing a book in a team with a VCS	Writing code in a team with Git
Book	Code Project
Book Section or Chapter	Project Folder or File
Main version of the book	`Main` branch, or `Head`
Download the book for the first time	Check out the project – `git checkout`
Update the book to the latest version	Pull changes, or Fetch changes – `git pull` / `git fetch`
Temporary version to try new ideas	Branch – `git branch`
Request to join temporary version to the main	Pull request, or Merge request – `git request-pull`
Join temporary version to the main	Merge branches, or pull changes to Main branch – `git merge` / `git pull` / `git fetch`
Save changes on the computer	Commit changes – `git commit`
Upload changes to the team server	Push changes – `git push`
Find who wrote a line of text	`git blame`

Git terminology

We hope you enjoyed this little foray into Git, and please let us know what topics we can explain next in this “For Dummies” series in the comments or on Twitter (@reviewpad)!

Git(Hub) Flow, Trunk Based Development, And Code Reviews

Adriano Martins — Fri, 18 Jun 2021 09:07:01 +0000

The right branching model will improve any team’s collaboration, quality, and speed. The wrong model will do exactly the opposite. These are the 3 most used branching models.

Name a company that develops software, there’s a very high chance they’re are using Git to source control their codebase. Actually, there’s a 77% chance, according to Smartbear’s State of Code Review 2020 Report.

There’s also a very high chance this company has a code review process in place. An 84% chance according to Codegrip’s Code Review Trends in 2020 report.

However, there isn’t a single standardized methodology to develop software using Git and Code Reviews because it’s highly dependent on the team and the project characteristics. It’s entirely up to the team to choose which methodology better suits their software development needs and goals.

We’ll go over the 3 main methodologies (also called branching models or branching strategies):

Git Flow
GitHub Flow
Trunk Based Development

The original: Git Flow

Rarely a blog post has such an impact in the industry as the one Vincent Driessen published on January 05, 2010, named A successful Git branching model.

In his post, Driessen laid out Git Flow, a robust and strict branching model that became the industry standard for software development for years.

It brought parallel development to the masses, created the perfect conditions for collaborative programming, and it scaled easily.

With it, many companies managed to grow large and efficient teams and to deploy very complex software.

With Git Flow, the repository is centered on the main and develop branches, and it is supported by feature-n, release, and hotfix branches, as described in this diagram:

Code Reviews play an essential part in ensuring the code is up to standard and bug-free when merging feature branches to the develop branch.

Git Flow allows for a very methodic and orchestrated software development but comes at a very high cost:

the sheer volume of branches and its overhead is a nightmare to maintain
teams have to be extremely disciplined otherwise they will end up with long-lived branches impossible to merge

The successor: GitHub Flow

With the advent of web apps and continuous delivery, a lighter and faster branching model gained traction: GitHub Flow. As you might’ve guessed, it was created and popularized by the very own GitHub.

It’s centered on the main and feature branches. Main is always releasable. Developers create a new feature branch to make changes. After reviewing these changes for bugs and code quality they will be deployed to production. If they cause problems, a rollback from main will take place, otherwise, the feature branch is merged to the main branch.

Compared to Git Flow, GitHub Flow is much lighter. Maintenance is very low because the only long-lived branch is Main.

However, GitHub Flow inherits other drawbacks from Git Flow. Undisciplined teams that keep feature branches open for weeks risk serious problems when trying to merge. Ultimately, a failed merge can leave main undeployable, and that’s a big red flag for continuous delivery.

The shift: Trunk-Based Development

Also going by TBD, Trunk-Based Development is somewhat famously documented at trunkbaseddevelopment.com. In this branching model, developers make changes directly in a single branch called trunk.

Trunk is deployable at all times. Changes should be summited daily. Unfinished features should be unexposed with the help of feature flags.

Yes, you read it right. It sounds like Yolo Software Development. There are is no code review in TBD, either.

The catch is that this method can only work in small teams, with seasoned developers, and pair-programming is highly recommended. The pace is very fast because there is very little, if any, overhead. The team must be very skilled and cautious because everything goes directly to the trunk.

This TBD model is actually officially called Trunk-Based Development For Smaller Teams. Despite its shortcomings, TBD for Smaller Teams is highly regarded by the software development community for its extremely lightweight workflow.

The seasoned: Scaled Trunk-Based Development

Luckily TBD has another trick up its sleeve: Scaled Trunk-Based Development. In order to operate at scale, this branching model uses short-lived feature branches with a life span of a few days (maximum) before merging to the trunk, which is deployable at all times.

Work in progress should be kept to a minimum, not only to avoid merging problems with long-lived feature branches, but also to make up for easier and faster code reviews.

Code reviews will guarantee only quality code is merged to the trunk and will allow for very early defect detection.

With Scale TBD, continuous integration is guaranteed, parallel development is supported, and quality is ensured with simple code reviews. It allows for quicker iterations with fewer errors, and it’s always deployable with very little branch management.

Own it!

It goes without saying that each team and/or product might warrant different needs in a branching model. Teams should take extra care choosing one.

Whichever branching model is chosen, it is very (!) important that it’s crystal clear to every team member what are the rules and steps in the workflow. Without it, any model will fail to bring out the best of the team and the product.

Code reviews for dummies

Adriano Martins — Thu, 03 Jun 2021 16:37:15 +0000

This blog has dedicated itself to the intricacies of code reviews. We’ve written about best practices, our review-centric philosophy for development, the case for simpler code reviews, and a few more topics of interest. We haven’t, however, taken the time to explain what code reviews are to the non-developers. Now is that time.

Think of a book.

Do you have one next to you? Do you know how it was made? Let us tell you about editing a book. When we’re done, you’ll know exactly what a code review is.

1. The author creates a draft

You can’t have a book without a writer, much in the same way that you can’t have code without a developer. The book can be of any kind. It can be a novel, it can be a collection of short stories, or even non-fiction and essays.

No matter how gifted the author, they can always use the help of a publisher to print and sell the book, but also an editor to work on the text.

Regardless, it’s up to the writer to produce a draft before they come in. It doesn’t need to be a finished book, by the way. For many publishers, the editor (sometimes two or more) will work right alongside the author throughout the writing process.

Developing code is similar. The developer creates the code and the reviewer looks it over for inconsistencies, problems, mistakes… Anything, really.

This is how we see things:

Author – Developer;
Book – Feature/task the developer is writing code for;
Editor – Reviewer assigned to this feature/task;
Publisher – The company or team.

2. The author edits their own work

“Editing is writing” is an old creative writing slogan that rings quite true. Any author worth their salt will never dump their uncorrected first draft on an editor. They will always go back to work, retrace their footsteps and improve what they’ve done. Ideally, the author will be able to answer any questions the editor asks about their work, and the choices they made.

In code reviews, every developer should be their own first reviewer, always checking their code while the decisions made are still fresh, so the reviewer will have as easy a task as possible.

3. The author will hand off the draft

When the author is happy with their work, they will then send it off into the wild. The wild, in this case, is an editor. This is a relationship that is sometimes described as adversarial, with both authors and editors feeling like they should have the last word over the text, because they are, in their own ways, specialists. This is, of course, pure nonsense. It’s in fact an exercise of co-ownership, where both parties profit from the text being of the highest quality.

One of the hangups people have about code reviews is quite similar to this. Developers, like authors, are fearful of the critiques and suggestions that reviewers and editors send their way, and they feel exposed when their work is in the hands of others.

There’s no need for this. Reviewing, much like editing, should be about collaboration, not confrontation.

4. The editor will fix mistakes, but, above all, they will make suggestions

The editor is a second pair of eyes. The author is living inside the world of their writing, which many times is a little too close to see the bigger picture. Someone else that comes in fresh, and is encountering the text for the first time, will be able to see elements that are missing and things that aren’t doing their job properly.

A reviewer will do the same thing for a codebase. They will find mistakes, of course, but the most important part of the job is to look at the code and try to understand it. To ask questions and make suggestions. The goal is to elevate the work.

5. The draft goes right back to the author

This is a moment of great anxiety. The work you put so much into is coming back with gasp criticism. Comments. Suggestions. It’s wrong, it’s all wrong. It’s terrible. You are a fraud.

No.

Of course not. If the editor is good at their job, and sensitive to the idea that the author is another human being who’s doing their best, the comments and suggestions should be light-weight, thoughtful, and humane. Whenever there’s an issue that is a little more complicated to follow, authors are encouraged to get in touch with their editors to discuss them and come up with a joint solution.

There is no difference for code reviews here. The reviewer and the developer will ideally engage in creative dialogues that will produce solutions that neither of the two could’ve come up with alone.

6. Time to make changes

Sometimes changes are small, and the first draft only gets slightly altered. Sometimes the editor will find a serious problem that needs a complete rewrite. Most of the time, the result is somewhere in between. The author will select which comments and suggestions to disregard and which to pursue. Some text will be rewritten, some mistakes will simply be fixed.

In code reviews, the developer will go through the same process. Not all suggestions need to be handled right away (or ever), and the reviewer isn’t the final authority. The suggestions and comments will bring forth new ideas and, ideally, result in a better code.

7. Do it again

The editing process only culminates when the book is ready to be printed. Until that printing press starts whirring, changes can and will be made. Other people will be proofreading the book as well, not just the original two. Most books will be read by assistant editors and proofreaders as well somewhere along the process, to ensure that as many issues as possible are ironed out.

Code reviews should be a continuous process as well. As long as the developers are making significant changes to the code, it should be getting reviewed as well. Other reviewers should definitely come in as well, allowing for collective ownership of the codebase.

8. Never be satisfied

What if the book is printed and you find a mistake? What if you want to update the book with more recent findings? What if you decide the story needs to be expanded? That’s what second, third, etc. printings are for. As long as the book is on the market, edits can and will happen. Expanded editions will be published. Revised editions as well.

That is the life of software development too. Software needs to be maintained and updated. Much more so than books.

And where there’s development, there should be reviews.

Let us know what software development topic you would like to see “for dummies” next!