Approaching Code For The First Time
Whether you are approaching a code base for the first time or you are doing a code review for another developer, reading code may be like reading another “language”. In school, you get extensive instruction on how to write code, but rarely hear about how to approach a large code base for the first time. And then you enter the “real world” and learn that reading code is as essential a skill as writing.
A lot of our new engineers see codebases that are significantly larger than what they were presented with during their undergraduate work. This can certainly be overwhelming. Organizing it all in your head is often impossible in active codebases. We share three tips with our new engineers to make new code less intimidating.
Step 1: Look for the Documentation
When you are looking at a new codebase, the first place to look is a README file. This text file is typically located in the root folder of the codebase. There are a few things that this document should include to make the process easier for the reviewer:
- What tools you need installed to compile this code
- How you can run the code or the context it is used in
- What the code is doing
- What different blocks are doing
Step 2: Look for Entry Points
Next, you will want to identify your entry points and programs that will be most beneficial to your review. We suggest you open up your code, in an IDE or another editor that understands the declarations, can do syntax highlighting, and can do code folding, so you can squeeze the code down into just the headers and stay high level. If you’re in C, the entry point is usually going to be your main() function in a main.c file. If you’re using the Arduino framework, the setup() and loop() functions in the INO file are the entry points. Python will have the package name and the entry point will often be in a file with the same name. You will find either a main function or code will start executing from the top of the file. If you’re in C sharp, you’ll find a Main() or OnStartup() function in either an Application.cs or Program.cs file.
If you’re in C++ or C, start in your header files, just see what things are being called and avoid getting mired down in details of how exactly each function is implemented.
Step 3: Take a 10,000 foot view
Once you have found the entry point, identified the main function and/or the top files, now you can see where the code is going. Taking notes in the form of a sketch or diagram block helps this process, and can also help to identify how things relate to each other visually.
When you are looking at code for the first time because you’re going to start developing with others, taking a look through the recent history and active branches in the repo can help you understand the code as well. This will give you insight on where active work is happening, what others are watching for, what is changing. Looking through this history may even provide you hints on what parts of the code are most important.
What To Ignore As Long As You Can
While reviewing code, there may be a temptation to fix all the things you see. Perhaps because they are not the way you would do them or you could recommend a better way. This is where we encourage you to pause. Here are a few things you can ignore.
- Coding style
- Libraries and other external components
- Whitespace changes (GitHub and other git tools can automatically hide these for you!)
- Identity and experience level of the author(s) of the code
- Things that linters will pick up, such as dead code, unused variables, etc.
In short, anything that can be caught or fixed by automated processes are better reviewed by those processes. If you don’t have these in place, we have some articles discussing the how and why of automation, too!
Reading code is as important as knowing how to write it. While this is not a skill that is taught, it can absolutely be valuable to your team and clients. And if you have questions about an embedded project you’re working on, consider reaching out! At DojoFive, we have talented engineers on hand ready to help you with all aspects of your EmbedOps journey. We are always happy to help with interesting problems that need solving. You can reach out at any time on LinkedIn or through email!
