As developers, at some point, we’ll need to deal with code created by other people. Sometimes it could be hard and tiring, but it’s not an impossible mission. So I want to give you some pieces of advice to do it without losing your mind in the process.
We are going to go through these approaches to create a good code legacy and how to deal with other people’s code and/or make teamwork easier. This is not an easy topic, but it’s really important to talk about it because it happens all the time like when you have to give some maintenance or start to work on a team.
The points that I mention below are the fundamentals, in my opinion, for having a better and easier experience in this situation:
- Observe and learn
- Test
- Think that you’re not the only or the last
- Use tools
- Choose your IDE wisely
- Document yourself
- Contribute to documentation
- There is no right or wrong way
1. Observe, Learn, and Ask Questions
First of all, when you are starting to work on a new project, you need to take it slow and don’t push yourself that much, there will always be a learning period, so it’s normal to feel like it’s not flowing at the beginning. Do not expect to know or understand everything right from the start.
Instead, I suggest you use the first days/weeks to prepare yourself to improve your understanding of the project. You can start by asking all your questions to the persons that are in the project; some of them probably have other pieces of information about it. Also, you can start to meet the code, understand the file’s structure and start learning about the naming standard for files, variables, components, classes, etc.
Besides the “research” work, I think this is also the perfect moment to set up your environment. I’ll recommend being sure that the environment is ready so you should be able to run/compile the project, this will be a critical activity, so it’s better if you take your time to do it. If some other developer is working on the project, don’t be shy and ask for all the information that you need, like libraries versions, dev tools that they use, and even about their IDE. Why they selected it, all this can help you to don’t have major problems with the setup, and also you will have a better view about how they were working.
This phase is for you to familiarize yourself with all the aspects that you can of the project, to establish a good understanding and communication with the team, and to prepare your environment.
2. Test
Once the project is running in your local environment, spend some time playing with it, this will give you a deep look at how it works, what it does, what information it uses or has, you will see the process, etc. As a result, this will help you to understand the tasks/histories because usually they were written from a high level or user perspective, so if you meet the project at that level, you will feel that you are talking the same language.
Furthermore, you will find any missing config or other errors if you get to break the app. These kinds of issues may appear at this point because, later, they will become a blocker.
3. Use tools
Some tools would help you, your team, and future/other developers of the project to have a softer transition into it.
Code Tracker/ Version Controller
If you have never heard about these tools, let me introduce one of the best ways to have code tracking and prevent code merge conflicts; the most used and the one I’ll talk about is git.
Maybe you are asking yourself, What is Git?. According to wikipedia.org, “Git is software for tracking changes in any set of files, usually used for coordinating work among programmers collaboratively developing source code during software development. Its goals include speed, data integrity, and support for distributed, non-linear workflows (thousands of parallel branches running on different systems)” (Git, n.d.).
Now that we are a little bit more familiar with it, I can tell you that Git will be your best friend in some complicated situations, like code loss or when you and someone else are working on the same project and need to merge your changes or if you need to do some roll back in a specific environment.
Well, actually, you can have complete code tracking, and it will make teamwork easier and also for version control.
Just so we can be on the same page, if you don’t know what version control is, according to Atlassian, Version control, also known as source control, is the practice of tracking and managing changes to software code. Version control systems are software tools that help software teams manage changes to source code over time. As development environments have accelerated, version control systems help software teams work faster and smarter. It will help to reduce development time and increase successful deployments.
Version control software keeps track of every modification to the code in a special kind of database. If a mistake is made, developers can turn back the clock and compare earlier versions of the code to help fix the mistake while minimizing disruption to all team members (Atlassian, n.d.).
Code formatter
First of all, we should talk about what code formatting or styling is. Is a set of conventions or rules about how the code should be, like tabs, spaces, variables names, indentation, etc. This standard formatting will make the code easier to read and understand, which will reduce the risk of mistakes, in addition to facilitating teamwork.
Numerous tools exist to automatically format code such that it follows a certain style. Automatic formatting enables higher code quality, especially when collaborating in a team and other people need to look at the code you’ve written. Many developers and organizations maintain standards of code formatting. Using these is highly recommended since the probability of finding bugs (if any) increases multifold.
Just remember that this type of change should be discussed with the team; you need to ask them before adding this kind of tool, as it may cause problems with version control, making it look like a file was changed when it was not.
There exist many language-specific tools for automatically formatting code according to a particular style and also for different IDEs as extensions.
4. Choose your IDE Wisely
One of the most important tools that we have as developers is our IDE. I know we can do it even on a plain text editor, but if you look for something more complete, you’ll find your best friend in the process.
According to Red Hat’s official website, we can define an IDE (integrated development environment) as software for building applications that combine common developer tools into a single graphical user interface (GUI) (Topics Understanding Middleware What Is an IDE? n.d.). An IDE typically consists of:
- Source code editor: A text editor that can assist in writing software code with features such as syntax highlighting with visual cues, providing language-specific auto-completion, and checking for bugs as code is written.
- Local build automation: Utilities that automate simple, repeatable tasks as part of creating a local build of the software for use by the developer, like compiling computer source code into binary code, packaging binary code, and running automated tests.
- Debugger: A program for testing other programs that can graphically display the location of a bug in the original code.
As we can notice, they give us more than just a text editor; we have more tools that are focused on development, which will make our life easier.
Also, you need to know that out there is an infinity of IDEs of all colors and flavors; you need to search for that one that adapts better to your needs and your way of working and maybe some other factors too, like supported languages, OS, automation features, plugins and extensions, even the impact on system performance. The idea is that you feel comfortable and can do your work effectively and efficiently.
Some examples of really popular IDEs are:
- Eclipse
- TextMate
- SublimeText
- VisualStudio
IDE Tools and Configuration
Some IDEs give you the option of installing some tools or libraries that will be useful for you and will make your work easier. For example, I use the TODO extension on my VS Code because it’s really helpful when I’m working on a large history, and sometimes I put some comments to know where I have to add some code later.
Also, this doesn’t just are for functional improvements because also you can personalize your IDE by adding themes and other visual settings. I have a favorite light and dark theme to switch between depending on the natural light to feel more comfortable.
There are extensions, and all of them have some specific uses, like letting you add languages, debuggers, and tools to your installation to support your development workflow.
5. Document Yourself
Documentation is not a synonym for failed programmers, designers, or non-technical people. Some of the largest projects actively suggest that the best place to start is documentation; I mean, when you are looking for some information, you know that the most reliable information is the one that comes from the official documentation.
You and I will not be the first or the last person that will be in this situation where we need to find or understand something. Others have come before us and made plenty of the same mistakes we’re likely to make, so if you research a little bit on the internet, you will probably find some information or related documentation. In that case, looking for documentation will save you some headaches.
The more you learn, the more you can grow, understand, and as a result, do. I’ll suggest that you check the official documentation of any tool or tech first. Still, also, I can tell you that there are some pages, communities, courses, blogs, etc., like StackOverflow, Reddit, Udemy, Pluralsight, w3school, and many others where you can find valuable information.
6. Think as if You’re Neither the Only nor the Last
Never lose sight that in this area, we are living constantly in change, so it is normal that the code passes through different hands during its lifetime; so you need to be understanding because nobody knows everything, nor is it perfect; there are many ways to do things and also sometimes getting to a project is complicated.
I’d like to give you a great example to make you suit this situation. Sometimes when we choose the name of a variable, we used to pick the first that we think of, but we don’t stop to meditate if it is easy to understand what it is. Let’s go to the other side, you are starting to work on a new project, and then you see a variable named “a” you will probably need to look at all the files or contexts to understand what it represents.
So try to code as if someone is going to be reading it constantly, choose names that are representative, add comments, etc., because you could be the next to work with that code in the future.
7. Contribute to Documentation
Sometimes I think that I should contribute more to the documentation. It’s easy to be a critic, sitting on the sidelines and criticizing a codebase, framework, or another kind of software project. Instead of doing that, get in and get involved.
There is no better way to learn something than to document it. After all, to document it, you need to know it. Make notes as you go along, then contribute to the documentation. If this doesn’t exist, be the first to start documenting, even if for no one else but yourself.
Perhaps there’s no documentation to speak of; a truly horrid place to be. But every project has to start somewhere. As you work through the source code, write down what you know.
This is not a common way to learn about a project, but it is very effective. Before we move to the next point, I need to clarify that when we talk about documentation, it does not need to be necessary tons of documents or technical or user-level documentation; of course, all that is helpful but even add some comments or descriptions in code could be really good practice and will be useful for when you had to work with it.
8. There is No Right or Wrong Way
The last and most important point is to be aware of your and others’ work. On occasions, it can be easy for us to be rude with our judgments, or unconsciously, we can think we know it all and that our expectations, concepts, and approaches are the true and correct ways to go.
I think that we as developers grow with our experiences, so it’s so natural for us to build concepts and ideals based on that, but it’s important to remember that in this area, we work predominantly by protocols, frameworks, and flexible tools which only suggest or mark some parts of the way but make you free of choosing the rest or how to use it, so, we are all free, and that’s not bad. Actually, you will be able to learn from others.
We can say that there exist many ways to do the same thing, and many, many of them are the right way to do it, so if something is not as you expect it to be, it doesn’t translate to it being wrong.
References:
- Atlassian. (n.d.). What is version control. Atlassian. Retrieved August 30, 2022, from https://www.atlassian.com/git/tutorials/what-is-version-control
- Git. (n.d.). Wikipedia. Retrieved July 11, 2022, from https://en.wikipedia.org/wiki/Git
- Topics Understanding middleware What is an IDE? (n.d.). Red Hat. Retrieved August 19, 2022, from https://www.redhat.com/en/topics/middleware/what-is-ide
