I started a year few years ago as a software engineer at nhub Nigeria, a Nigeria tech workspace and startup. I previously had 2 experiences as a project manager in IT departments so I had an idea on how to make software. But I learned many new things becoming a developer myself. Here are some.
Writing code that works is easy
Before applying to software engineering jobs for the first time I made some online trainings (mostly freecodecamp, that I recommend). I wanted to show my motivation, and what I could learn in a couple of weeks.
When I started my new job, my first challenge was to write code that works. Which means code that actually does what the specifications say. Almost everything was new. I learned about JWTs, how to connect to a database with Node.js, how Vue.js framework works and technical elements like these.
But after a couple of months writing code that works I realized that this was not the most difficult part. The hardest part is to write code that other people can understand.
Writing good code is harder
So, how do you write good code that doesn’t just work but follow good practices?
First what is good code? Some elements that help considering good code to me.
It’s understandable
Good code is understandable by your co-workers (present and future) and your future self. Everything will be easier if more than one person at a given time can understand what the program does.
For instance, you can start by taking time to name variables, functions or errors the most clearly you can. It sounds easy but a huge amount of time will be saved if functions are well named (get, data, id should be banned). Worse than too generic, the function does something different than the name suggests. A function getSomething that also sets something inside it and thus has a side effect: not cool.
Another aspect is an effective code architecture, split by files and by function. So that people can retrieve what they are looking for. It also helps unit tests if you have functions that are well separated and can be tested in isolation.
Errors are caught
Your code is good if it doesn’t break each time there is an error. Which means there is good error handling. Indeed, errors are part of the software, it could come from many different elements. A user using the software in a way you didn’t design for. Data that don’t have the same format as you expected (via user input, API changes, etc). The number of concurrent users that you did not have in development mode or even network errors.
Even if you can’t plan for every error that will appear, you can have a more generic error handling strategy for each case it doesn’t go as expected. For example, for every route of your API, you can encapsulate all the things done in a try catch that will log the errors and send a generic error message to the client.
It’s documented
Because you won’t be here forever. Plus you want to save your time answering the same questions again and again. It’s easier to take the time to write how things work. A good start is having a readme up to date, an architecture diagram and comments in the code when something is not clear (a common advice is to explain why and not how).
It’s maintainable
Which means the product can evolve, you can add features, or enhance part of the product without breaking everything and taking too much time to refactor. It’s a subtle art of going fast to iterate (which introduces technical debt) and developing thinking about the future to be generic enough for evolution.
How to write good code?
Once we have an idea on what good code looks like, how to help people applying those principles?
To me there are 2 main mechanisms (other than the good will and the knowledge of the developers): the conception and the code reviews.
Conception
As a project manager, my first responsibility was to define the scope of the project I was working on. You need everyone aligned on the scope, because the rest will depend on that. You can’t discuss the budget, the planning, the risks, the resources of the project if you are not clear on the scope.
As a developer it’s the same: the first thing to do before even thinking about the technical conception is to define the scope of the feature. You usually do it with the product owner/manager in an agile organization.
Is this part included in the sprint or not? Can we reduce the scope to have something working (even not perfectly) at the end of the sprint? Is this part core to the feature or a nice-to-have?
Once you have a clear scope, you can start to do the technical conception. You can discuss: the name of your components, your API routes, the data format and what part of the codebase will be affected for instance. You don’t need to discuss every implementation detail or spend hours discussing a function name. But think about the overall architecture and how
different parts of you application will be connected. It will reduce the subjective decisions one person will have to make and thus improve the readability and the quality of the code.
Code reviews
In the classic git flow, every new feature is developed on a feature branch and a pull request is made before merging the work into one of the main branches. The code review is the process of checking every change made to the code (called git diffs). People can then discuss if something is not clear, or not optimized (for the readability). It‘s hard at the beginning and it takes time but it will save way more time in the long run.
This quest for readable, clean and maintainable code is never finished. I don’t think that even the most senior developer writes perfect code 24/7. But reviewing and letting your code being reviewed greatly helps at the beginning of your career.
Top comments (0)