When you learn a new language or a framework you almost always certainly start fresh with a new clean project aka green field project.
In the industry you rarely get the chance to do so. You will have to start with code which has already been there for a specific time. These projects are called brown field. And brown not in a good sense. Brown can mean mud to sh…
When studying other people’s source code You can feel overwhelmed by a lot. so it’s important that you get your hands dirty as soon as possible.
Here are some tips how you can start to work with a code base right away:
Table of Contents
Create a feature branch and checkout the code
I assume that the code is under some kind of version control. If that is not the case you need to do that first. And please start to wonder why you joined the company in the first place. Because chances are high that it wouldn’t have passed the Joel test before applying. If you are not allowed to use a version control system please leave immediately. “Lowering the standards is the key to happiness” should not apply to software engineering!
But back to the topic: if you have your own local copy in your own branch you can use your favorite IDE to browse the code and start tinkering with it.
Add a .gitignore file
In case the version control system is git you should check if a .gitignore is present and if not add one.
When working with Perforce you can use a .p4ignore file.
Add a README.md or README.rst
A README file is a good starting point to gather information about the purpose of this project, key stakeholder and links to further documentation.
Add comments or rewrite unclear comments
Adding comments is non-invasive way to improve code and get your hands dirty at the same time. But please just add meaningful comments which explain concepts and design decisions.
Remove unused code blocks
Seems to be a no-brainer: commented out is already at the verge to be thrown out, so no big deal. When we have version control in place we can always go back and retrieve those lines anyway. If it is working code fragments consider using gists or something similar.
Format the code
Hopefully there are some coding standards around so that You can avoid the fight over tabs vs spaces or two vs four spaces. Many IDEs have auto-format options but they are not used very often. When you are working on a file make it a habit to reformat the code.
Add tests or fix broken tests
Very often there are no tests at all inside a software project. So fix it.
Just add the first test which starts the program with some reasonable parameters. Most of the time it is the easiest way to add an end-to-end test which tests the system from the user perspective.
When working with web technologies try Selenium, when dealing with Android try some Espresso. Spending time to learn some unit test frameworks is time well invested.
Further Reading
Why you should use PyHamcrest in testing
Add Continuous Integration
When the project is under version control and some tests are in place you should start to add CI/CD. In an open source / github project you can add Travis CI very comfortably. In a closed source / company project you have to figure out if a CI/CD systems like Jenkins or TeamCity is already in place.
Further Reading
How to use tox to test your code on multiple platforms
How to add Travis CI to your github project
Add logging or improve existing logging
Some projects are missing some meaningful log output as well. Why do we need logging? In many cases you won’t have access to the software to be able to debug the program directly. So you need some error logs for reproducing the error case.
Check if there are enough log statements. Check for the right amount of log statements. Is the application to verbose or to quiet? Are the log levels used appropriately?
Further Reading
Lock dependencies
Projects often use external software dependencies. Very often programmers forget to pin down the exact version with which the program is able to run.
This can lead to breaking changes when someone is using a newer version of a dependency. You might not even be able to get the program running ever again.
In Python you can do a
pip freeze > requirements.txt
from a working installation. Even better is the use of pip with venv or pipenv
If there is no dependency management in your project yet, you need to add one!
Final words
Let me re-phrase: “Upgrading the standards is the key to happiness!”
Further Reading
Review – The Passionate Programmer
Review – Lessons learned in Software Testing
