Etiquette

Source control

Using source control is by far the earliest-and the most common-decision any software engineering team may make to arrange work and minimize risk of loss on the long run. The purpose of source control is to accumulate the evolution of the code; the code's, to create the product; the product's, to make the revenue. Still, merely putting the code into the source control without any system isn't worthy of a sophisticated person.

We will stick to Git here as it's by far the most common option. If it happens that you use a different tool, please consult the following advice nonetheless.

To never interrupt the work, use branches. It is one of the ways to ensure any changes you make will not interfere with those of another person. Prefer creating branches based on the main branch and make sure your local copy of the latter is up to date by pulling it.

Together with the team, establish branch naming convention that would help you solve the problem of feature lookup and code review. A good tone here is to name branches in a way that corresponding work items can be discovered easily. If branches are named after unique identifiers of the product backlog items, arrange at least read access to the latter for every team member who contributes to the code. Stick to the naming convention and make breaking this rule a rare exception rather than a norm.

Avoid committing to any branch that was not originated by yourself; if a need arises to take over the team member's work, take time to consult with them in person to plan the course of action and the expected outcome. If it's merely a matter of code improvement, restrain from doing it yourself and choose to educate the author instead. There is no use in doing all the work yourself and scolding the team members, as it eventually makes you the least performant member of the team. Consider elevating your team members instead, and invest time into active personal help.

While called “feature branches”, those by no mean should directly mirror features as defined in product backlog. Create feature branches in context of engineering, where each change is limited in depth of technical scope and breadth of impact on the codebase. Otherwise, a feature branch that changes half of the codebase is most likely to cause trouble for the rest of the team.

Make short-living branches to keep up with the pace of the team. A branch with compact changes that lives no longer than half a day before code review and just as long before being merged into the main branch helps the team to maintain fast cadence of feature releases.

Write comprehensible and easy-to-understand commit messages, as it will help your fellows recognize those in Git history later on. Along with “fix #1”, provide more information, whenever comes necessary, in the commit message body that goes on the next line after title. This is especially important when the format of a configuration file or structure of modules changes, and it is expected to be present along with the update in configuration-specific or module-specific documentation in the codebase.

A prominent mark of skill is to keep changes in a feature branch within one commit, when the source control tool allows it, like Git does. A feature branch that consists of one commit, when merged into the main branch, makes history comfortable to navigate and manage; and emergency removal of any feature becomes trivial. Having many commits per a feature branch makes the history hard for an unfamiliar person to comprehend, and provides rich soil for merge conflicts.

The pull-request (or, in Gitlab terminology, merge-request) isn't a Git feature, but the one of Github or Gitlab, or any similar tool of choice. While proper behavior that an engineer demonstrates in pull-requests is described in detail in the article about Code review etiquette, here follows specific advice: create a pull-request as early as you have branch and first changes in it; it will present your care and sympathy for others, especially the team members. To avoid confusion, mark a pull-request as work-in-progress when appropriate.

Following this advice, you will have your team's Git workflow fast, the features atomic, the shipping regular, and the emergency rollbacks safe. You will have smaller features, in context of engineering, make bigger features, in context of product. The code review will become a straightforward and time-efficient process, and increasing code quality will become real.

Code review etiquette

In a balanced and mature software engineering team, code review is a regular practice. In this article, we will learn the characteristics and attributes of proper code review. For convenience, we will refer to Github's pull-request feature, although it is possible that your tool of choice is different; in Gitlab, for one, this feature is called “merge request”. In the text below, we will use the abbreviation “PR”.

First and foremost, you should make your progress visible to the team each time you undertake a perilous attempt to implement a new feature. Therefore, create a PR as soon as you have a feature branch and, if already, first changes in it pushed to the remote. Early display of the progress makes it easier for your fellow engineers to synchronize their effort, avoid duplicate work, and become tactically aligned.

Mark a PR as “work in progress” or “WIP” to avoid premature review. It is a sign of good manners and proper behavior towards your team to explicitly signal the status of a PR. To emphasize this fact, you may also use a “warning” emoji and accompanying text on the first line in the description.

As a reviewer, always take the “WIP” status into consideration and restrain yourself from commenting on unfinished work. If it is necessary to point out potentially risky solutions that the author chose to implement, contact them directly, and discuss technical or style decisions and appropriateness of those. There is no use in leaving comments before the work is done only to find them obsolete or, worse, having caused unnecessarily negative effect on attitude of the author.

As an author, describe the changes thoroughly, in technical context and in what it adds to the product. While the codebase undergoes the process of maturation, it becomes increasingly harder to track technical and architectural decisions, and the traces of those are necessary. Putting information about feature is therefore essential for the success of the team as the product and codebase increase in scope and size. As a reviewer, expect this and ask the author to provide clarification in case any of the aforementioned information is missing.

As an author, put illustrations of “before” and “after” in the PR description. Having visual evidence of work done and decisions made makes the PR easier for reviewers to assess and leaves incomparably more time for the deliverable work to be done. A short screen video or animated GIF may win attention and demonstrate your attention to As a reviewer, reward authors who add images and mention this in positive tone and noticeably, so that other fellow engineers begin following this practice, too.

You should be polite and courteous, but also be helpful and provide the necessary help for the author or reviewers to successfully complete their work. Long-winded arguments that are difficult to follow are, by all means, to be avoided. As an author, you should be receptive to any feedback given on your work, and be ready to discuss it; as a reviewer, you should provide enough information for the author to justify your opinion. Any information that is helpful should be added to the comment. If it is a reference to documentation or guidelines, do not merely say, “See guidelines”, but provide a link to specific section of it that describes the standard and makes clear what is wrong in the code. If it is a wrong technical or architectural decision, do not say, “It's bad”, but illustrate the potential outcome and the right solution by referring to documentation or publication, old PR or a commit earlier in Git history.

In comments, follow proper tone, grammar and formatting. Write in a way that is comfortable to read. If it's a change request, it has to be clearly visible, yet not offensive to the author. Avoid using backticks, which format text between them as code, to put emphasis; use them to mention references to variables and expressions in the code. Avoid putting excessive about of bold or italicized text, as it creates misbalance and lack of contrast, and therefore makes the text lose its power. When need to give a piece of code as an example, even though it might be one line, put it as a code block wrapping lines in three backticks; a sign of courtesy is to specify the language, so that the code becomes highlighted and can be comfortably consumed at a glance.

Let the author of the PR merge it, suppress the urge to merge it yourself. The author may have untracked changes that are not reflected on the remote branch, or they may be willing to rewrite history within their own branch to keep changes within one commit. Regardless of circumstances, even when the tempo is fast, or there is another teammate who depends on author's changes and cannot proceed without them being available in the main branch, restrain yourself from breaking this rule. An exception, however,may be made when you have an agreement with them that you will do this in lieu of them.

Following this advice, you will have the code review process that every member of the team loves and looks forward to. You will have shorter PR-to-merge times, healthier relationships in the team, the ambient education running perfectly, and the engineers sharing knowledge freely. The team-wide conversation will become positive and sought-for.

Team chat

Even when an engineering team resides in an office space, team members prefer using a team chat software to demonstrate their progress, find resolution to interpersonal misgivings and undertake team-wide tactical planning. Having a team chat is as inevitable and expected as talking itself, and mutual bodily proximity does not neglect the need in the former. In the text below, we endeavor to familiarize ourselves with the rules of good behavior in team chat.

First of all, when just introduced to a new team chat, make an introduction of yourself in a channel where it would be most appropriate. When doing so, restrain yourself from jokes that general audience may not understand, and skip facts that are considered irrelevant to your new duties, but make effort to make the introduction memorable. Avoid mentioning your age, years of experience, or social status; instead, use this opportunity to articulate the brightest attributes of your personality. A gesture of gratitude towards the reader is to keep the introduction within three sentences.

It is of great importance to write comprehensible messages, use simple words, and follow straightforward narrative. Each new sentence has to be a conclusion of the preceding one. Jumping from one point to another displays the author as indecisive and irregular person; this pattern should be disavowed by a sophisticated author. It is recommended to follow Rolfe et al.'s reflective model, that is, effectively answering three questions:

  • what?
  • so what?
  • now what?

With this in mind, begin with the original supposition, which might be a problem mentioned or question asked before. Then, express your opinion, potential outcomes and possible ways of settlement. And finally, declare your intentions and propose a plan of action. This, executed in friendly tone and genuine intention to help, will turn any conversation into a success.

However, you should not confuse pseudo-profundity with communication prowess. Be an easygoing person, for such a person quickly earns respect of the peers and makes a role model for the rest of the team. It is no less than art to welcome questions and provide valuable answers, yet retain one's own priorities and not strew along gurgling concoction of peers' adjurations.

Although a minor recommendation, it's not to be overlooked that you should format the text properly. It means that, most often, plain text may be fine, but when you aim to give some part of the message an emphasis, make sure the formatting matches that part semantically. Do not format as code something that isn't code, or as a quote something that isn't a quote. Certainly, do not overuse formatting to a point where the text loses its contrast and strength. We discussed this earlier in Code review etiquette chapter, so it is recommended to consult that text as well.

Similarly to a casual verbal discussion, you should keep as close to the primary subject of the conversation as necessary to achieve the initial goal. It is a sign of decency to come to a decision, sometimes referred to as “next action”, before switching the context of conversation, or letting the companions do so. It is certainly possible that complementary questions may arise in the course of conversation, in which case you should provide, or expect from a more suitable person to do, as succinct reference as possible and put a clear “end statement” that would bring the conversation back in context of the main topic.

With these points in mind, you can not only succeed at a casual conversation on team chat but, more importantly, be of great service to fellow engineers. Good luck!