Code that fits in my head – part 3

For the third and final article in this little series of selected lessons from Code That Fits in Your Head: Heuristics for Software Engineering by Mark Seeman, I look at some tools and ideas that can help you manage your work processes when you code.

Use your IDE!

If you are writing code, you are most likely using an IDE (Integrated Development Environment). These often come with tons of handy features for writing software.

A well-known feature in IDEs is code inspection, which highlights areas with room for improvement or possible problems. These will not necessarily prevent the code compiling, let alone running, but might be an indicator of unwanted behavior. One can think of them as a second pair of eyes. To prevent possible unexpected behavior, treat warnings as errors. To force developers to do so, most IDEs provides an option for doing so.

Another IDE feature is auto-completion. You’ve probably seen this as it is quite hard to miss. While you are typing, the IDE shows you suggestions of what you might wish to type based on the context of where you are currently writing. This can not only save you from typing out long class names – and misspelling them – but also hint at possible methods or types appropriate for the context.

Lastly, IDEs can offer code navigation. Finding the implementation of an interface usually requires navigating the whole project structure using some tree-view panel. This can be cumbersome with improper file structuring and/or naming. To avoid this, you’ll most likely be able to right-click on an interface and see “Go to implementation”. Many other handy navigational features are most likely available.

This is just a few of the tools you will find in your IDE. The point is that it is a good idea to spend some time getting familiar with these type of features in your IDE, as they can save you a lot of time in the long run.

Documentation

Many people write comments in their source code. However, comments inside a code base might be overlooked when refactoring and can easily end up being outdated. Furthermore, long comments fill the screen and take focus away from the most important thing: the actual code. Often comments simply describe what the method below them does. This information should instead be expressed using a descriptive method name.

Comments should therefore only be used for information that cannot be inferred from types, class names or method names.

Version Control

Commit messages are often seen as a hassle and an afterthought, which often results in messages along the lines of “fixed the problem” or “improved the code”. But does this help you understand what happened in the commits? Sometimes a commit message also describes what was changed. This is practically useless, as the whole purpose of using version control is to document changes. Therefore, the commit message should be used to explain why something was done. It could be that a conditional changed to fit a new business rule, or a new scenario was covered by a test case. In both examples, what changed is visible due to version control and the how is present in the commit message. Writing the commit message in current tense instead of past tense saves on letters and makes no difference in expressivity.

When you write code, you sometimes discover that parts of the previous work you have made is wrong. Version control provides functionality to simply roll the code base back to a previous point in time. However, this only works if such a point in time exists. If the previous work was only committed as a single commit containing many changes, it can be cumbersome to navigate all the changes and manually pick the things you wish to remove or keep. If you make small, frequent commits instead, it becomes easier to roll back to a previous commit and often makes it easier to write commit messages.

When working on a feature, you may sometimes wish to test an idea that involves changing parts of the code base substantially. For such a scenario, branch off to a new branch, and then implement the idea there. If the idea proves to be successful, simply merge the branch into the previous feature branch. If not, change to the feature branch and delete the unsuccessful branch.

Merge conflicts can be quite the pain, especially with many people working on the same part of the code base. Likewise, when software is in its early stages, there can be situations, where one feature blocks another, forcing one developer to wait on someone else to finish their piece of code first. A solution to this is to merge with the master branch often. If the feature you’re working on is not done, then hide it behind a feature flag. Make sure it is not accessible to the user of the software, so they do not encounter unfinished code. To be able to drive the behavior of a feature using integration tests, simply flip the feature flag for the given test.

When the day is reaching its end and you have yet to commit your code to master it can be tempting to simply commit whatever you have, whether it compiles or not. Doing this will most likely result in one of more of your fellow developers wishing to kill you. It is also a sure way to have developers not wishing to touch the broken code, which results in only some developers having knowledge of certain parts of the code. Always make sure that the master branch contains code that compiles, so it is ready to be picked up by another developer. Make sure all developers dare to work on all of the code base.

Having implemented a feature, it is then time to merge it to the master branch. It is always a good idea to have a second set of eyes look at your code, as they might spot small mistakes or points of improvements you yourself have missed. They should look at the readability, as if the code is not readable, how will another developer be able to continue working on it? Whether the code works or not should be reflected by the fact that it compiles and passes tests. When you review code by others, remember that it is not only about finding flaws in the code. If you see something that you like, remember to give credit where credit is due.

Conclusion

This marks the end of a 3-part blog post series highlighting what I think are the most relevant points made in the book Code That Fits in Your Head: Heuristics for Software Engineering by Mark Seeman. The book covers many more topics than what I have fitted in this short series. If you are new in the field, or perhaps just wish to become a better developer, I suggest you give the book a read.

(Background header image courtesy of Ross Sneddon)