All too often in my professional career, I’ve been tasked with working on legacy code. For those of you unfamiliar with the term, “legacy” in the computing sense refers to old software that has been passed down. Often, legacy programs work just well enough to keep, but not well enough that they don’t require maintenance. Thus, the same code often gets handed down to a company’s next generation of programmers, who must then figure out what it does and how to perform updates without breaking it.
Unfortunately, many developers don’t program in a courteous manner. Courteous coding is the practice of leaving cues about your code to help the next person who works on it. He or she can then spend more time programming and less time deciphering your program logic.
It’s more than just professional courtesy, though. Coding standards are important from a business standpoint because, as the folks at Sun put it, “80% of the lifetime cost of a piece of software goes to maintenance,” and, “Hardly any software is maintained for its whole life by the original author.” By making your programs easier to read and understand, you increase their long-term value.
Whether you’re a developer or you employ them, then, it’s worthwhile to know these seven keys to courteous coding.
- Use meaningful names. File, variable, class, and function names are only as instructive as you make them. Ideally, they should accurately but succinctly describe the information being stored. Using names like “$temp” and “script.php” leaves the next programmer in the dark as to the intended purpose of your work.
- Leave meaningful comments. Every modern-day programming language gives developers the ability to comment out areas of code that are removed from the flow of execution. Naturally, comments are often used to debug and deactivate code. However, it’s worth noting that they’re called “comments” for a reason. Be sure to use them for their intended purpose. Leave notes for the next programmer explaining how your code works and they won’t have to do as much guesswork.
- Sign, date, and describe your program. In the same vein as leaving comments, it’s often useful to leave details of when the program was written, by whom, and for what purpose at the top of the file. Much like other comments, this helps the next programmer put your code into context. Also, if you’re still available to the company, he or she knows who to ask for help if needed.
- Use a standard casing convention. Exactly what casing convention you use is a matter of personal preference. For example, you might make all of your variables lower case, while “camel casing” all your functions and methods (i.e., capitalizing the first character of every word but the first). This enhances your code’s readability. Whatever convention you choose, however, any enhanced readability will be lost if you break from it, so be sure to case with consistency.
- Use proper spacing and indentation. Language interpreters and compilers strip out white space, so things like line breaks, spaces, and indentation are largely just tools for human understanding. Use them liberally and consistently. Add spacing around things like conditionals and variable declarations. Indent blocks of code once for each block. If you arrange your code neatly, the next developer will thank you for it.
- Maintain clean code. Even if you use proper spacing and indentation, your program may be difficult to read due to large amounts of clutter. Once development is complete, be sure to go back and delete unnecessary elements. Things to remove include repetitive declarations, output statements used for testing, and commented code that is no longer useful to keep around. (Note: Jesse over at The Future of the Web recently clued me in to the term “code refactoring”, which describes the practice of cleaning up your code for future use.)
- Provide documentation when necessary. Particularly large programs can become labyrinthine in their complexity. Documentation is the road map that leads users and programmers through it safely. If your code is complicated enough to require it, take the extra time to write out its usage and function.