Writing Good Code, a Guide for Young Software Engineers

There are a few simple rules that help to write good code: it stays maintainable, it is stable, and it solves a problem. When one of those attributes is missing, you are not doing a good job.

What I found from my experience at Vertalab is that even a junior software engineer can show good performance by following those rules.

Know what you are doing at any moment of time.

It is so obvious, but people forget about this and might spend hours on something useless with the feeling of doing the right job. There are steps to follow to help keep you focused.

Every task should be added to task/project management tool. A small, 5 minute fix? Yes, add it as a task. Another point is to keep status of the task up to date. When you feel like you are not sure what you are working on — open the assigned tasks and you will see the picture. If no assigned tasks are available — ask for assignments.

During Ruby On Rails lessons, I ask my students to use stickers to show what they are working on. At the end of the day, results are much more viable when you have a pack of stickers with completed tasks. You can see it, show it to others and enjoy the results.

Understand the goal of your current task

Every task has a specific goal and is expected to reach its aim. It could be a new feature, bug fix or improvement. Before writing any code, think about the following: Why do you do this task?

Possible explanations are: “it will be cool”, “because I found a nice library and want to use it”, “everyone has this feature already” etc. Those could be good or worthless reasons, depending on context of your project. Clarify the reason. Write it down and be sure you understand it. What to do if you disagree? Argue with your team by providing strong thoughts to correct or accept a provided goal.

Build a solution

In most cases, building a solution is easy when you can describe with simple sentences what you want to achieve. So that solution is inside task description. For example: “change home page title to “New homepage””.

Sometimes your work may impact existing systems and may affect different parts of the project. In this case, it is important to draw algorithms with detailed steps of what you are going to do. Use paper first, and then the solution can be presented as a schema or checklist. The main goal is to split a big task into smaller steps and describe what exactly should be done with simple, easy to understand sentences. Try to think how your work could affect other parts of the project and write down how you plan to handle this.

For example, think about a task for a ticketing solution. Your task is to add a new feature to allow a ticket refund. How much to refund to the customer? Ticket price, but what about coupon code applied, what about fee from payment processor? What will happen with stats for the event? What if the customer got Silver status with this ticket by reaching a specific number of tickets bought and he now wants to return this ticket? Will he keep Silver customer status? This is a complex thing and there is no way to start coding until you think about all those scenarios.

After you write steps in normal language, the next move is to go further and translate those steps into technical-ready solutions. At this point, you can specify updates needed in the data model, relations, and new methods to write. Sometimes the only thing you have to do is to properly configure existing parts.

Tips on how to find solution

Think. Google. Think. Write down ideas. Read documentation. Read the sources. Use the power of open source.

At this point, it is a good idea to build a proof of concept as a separate project.

If you can’t find a solution for more than 1 hour — ask for help. Before asking for help, try to collect and organize something to talk about. It could be ideas, links, solution that you do not like. Anything other than a verbal explanation will help a lot to your colleagues to jump into the context of your task.

It is OK to go back to the task description, rephrase it and start thinking process from the beginning.

Share and discuss your solution

It is important to review your solution by other people. A quick view on a solution even without knowing all the details may result in interesting comments and questions.

Be sure you have something to show — schema, detailed to-do list, proof of concept etc. Remember that the other person is doing something and is focused on his task. When you ask to review your solution that is poorly described, you will then spend more time explaining your solution. As a result, you will waste time for yourself and for your teammate. Be kind and respect the time of your colleagues. Focus and do the best to help them to help you.

You might keep the loop of think/share/discuss as long as the solution becomes clear.

Write code

Any developer can write code now as there is a clear solution. What you should remember is that there is no need to rush. Carefully read documentations over again and follow steps from your solution.

You know how to write classes, methods and how to connect things with code. If not — read docs.

Review code

One more step is to do code review. Note that the person who does code review can be from the same project, but ideally, should not be. As you get feedback or questions about your code, discuss them and work together to improve your code. There are always possibilities to learn from other people.

As you see, coding is a team effort. To write good code, an engineer has to respect others and accept feedback not only from more experienced team members but from everyone on their team.

Happy coding!