Making Your Code Easy to Read
Making code easy to read is not only a kindness shown to your fellow developers, but also to future you! If you read our previous post in this series, you should know the basics on how to read code and the important things to look out for. With just a little effort on the front end, you can make reading your own code even easier.
Write up a README
If your project doesn’t have a README, that’s the place to start. It provides a one-stop explanation of what your code is for and how to use it. The README will be the very first place an external developer looks to for information on your code.
As you write your README, there are sections that should be included for each project.
- Point of contact and code owners
- What a developer needs to set up their environment to build and test the code
- External dependencies the code relies on
- How to hook up and flash the related hardware
- What is included in the continuous integration pipeline
- Links to the project documentation
- Links to data sheets and other documents stored outside the repository
READMEs use a lightweight language called Markdown. For a quick overview, check out: The Benefits of Markdown. Creating a standard template that builds on your team’s expertise and knowledge of the codebases will help to make this process nearly automatic when starting a new project.
Document the Code Itself
Include some documentation for each function. Place your comments about why you made decisions within your code. As we mentioned in earlier posts, this gives reviewers a chance to see your thought process as you wrote the code. As you are documenting code, note that while it has become popular to think of variable and function names as “self-documenting”, it’s highly recommended that regular language is used to explain what each code block is doing. This greatly improves the readability and approachability of your code. If your team uses a documentation engine such as Doxygen, you get a double benefit of having a standalone reference available.
Accurate Commit Messages
When making a change, explain why you chose this way, what the intention of the pull request was, and what got in the way of choosing a different path. Especially if you decided not to use a standard way of creating a solution. Explain the reasons that brought you to make that decision over others. Making small, frequent commits along the way can also prove beneficial to see your thought process throughout. Have you ever been stuck scanning through old commits to find a tidbit of information? I have, and accurate commit messages can help ease the headache.
Small, frequent commits: We suggest that your team start separating your reformatting changes into separate commits so you can just skip that commit as you are reviewing PR’s. Having precise commits also makes any git processes down the line much more efficient. When cherry-picking, you know exactly what changes you are taking. When rebasing, you know which code is being edited, whether it’s needed or not and won’t need to consult the git diff as frequently. Here is an article we use to reference best practices for commit messages.
Pull/Merge Requests: Pull requests can become burdensome to review if you need to take each piece of code and analyze for yourself what is happening in the changes. Your coworkers will surely be happy if you take this into account when creating your own PRs! Not only will documentation and updated README’s help make this clear, but the accurate commit messages will give a concise timeline of your changes, as well allowing your reviewing coworkers to immediately see what you’ve done rather than figuring it out themselves. Maybe they’ll even buy you a coffee for making their workday easier! (Probably not, but it’s worth a shot, right?)
DojoFive brings modern tools, techniques, and best practices from the web and mobile development environments, paired with leading-edge innovations in firmware to our customers to help them build successful products and successful clients. We have talented engineers on hand ready to help you with all aspects of your EmbedOps journey. Bring your interesting problems that need solving – we are always happy to help out. You can reach out at any time on LinkedIn or through email!