One of the seemingly simplest tasks in programming is sometimes one of the hardest: naming variables. One day, a coworker of mine was asked by numerous people throughout the day to help come up with meaningful variable and function names that applied to their specific situations. By the end of the day, she was mentally exhausted from the all of the thinking and internal deliberation involved.
This mental struggle seems to be present when naming any variable, function, class, property, enumeration, or namespace. It’s always difficult to come up with a name that
- Represents the data accurately
- Is verbose enough but still concise
- Makes sense to you
- Makes sense to any other team members that will come across your code in the future
It’s important that all of these criteria are met if you have any hopes of maintaining the software moving forward.
This struggle of my coworker that day inspired me to write a song about the whole process of naming variables while writing code. The song portrays a developer (myself) trying and trying to write code, but I need help naming variables. With none of my coworkers able to help and getting caught up in meetings, it seems like I can never make any progress! It’s just one of those days…
You can find the song below:
I recently spent a period of about 2 weeks chugging away at documenting a large module of our application. Many of the business rules had never been documented before, while some had been established during the last release. It seemed to be a sort of “business rule soup” trying to wade through all the existing (and sometimes out of date) documentation and consolidate it into a up-to-date module document. Through the process, I came away with 6 reasons why it is so important to have good, thorough documentation:
- The people testing your software can know how to test it. Obviously, you want the people testing your code to know how it works so that they can test it correctly. Out-of-date documentation or documentation that is not put in human readable terms (e.g. someone off the street can understand what’s going on) is not going to help your testing staff. The more business rules you document, the more bugs the testing staff can find! How will they know if there’s a bug if they don’t know how the page is supposed to work?
- Other people on your development team can learn about how your software works. With many large teams, it can be difficult for every member to be familiar with every single piece of the software. With good documentation, if a team member with no experience working on your software is assigned to add a feature to it, they can simply refer to your documentation to understand the intricacies of how it works, and the business rules it should enforce.
- You can remind yourself of what you wrote. Let’s face it. People sleep. We forget things. If I work on a feature back in January, and November comes around, chances are that I probably won’t remember what I did back in January. With good documentation, I can refresh my memory of what exactly I did in the code, without having to trace through huge bits of (probably uncommented) code to try and understand what all is going on.
- People new to the project can learn how it works. Pretty self-explanatory…documentation is great for onboarding new members to projects. If they are going to be writing code one day, they better understand how the existing code works, first!
- You will find bugs in the software. When thoroughly documenting a piece of code, especially ones that haven’t been documented correctly, it will require you to heavily test every single business rule present and determine the source of every single piece of data. Sometimes you may find that some rules are partially enforced, or maybe aren’t enforced at all. Perhaps people thought the code behaved one way, but after attempting to document it… Woops!! Doesn’t behave that way!
- You will have less false bugs reported by the testing staff. It’s important that business rules are documented, but they must be correct! With thorough documentation that is correct, there will be little chance that a bug will be thrown at you, when the real problem is incorrect documentation.
See! It’s pretty important after all! Although documentation can be a bear to write at times, it can be your best friend in the long run!