The Rules for Writing Maintainable Code

[magazine]
Volume-Issue: 

Ensure good logging of code execution: Effective debugging requires good code logging. You need evidence of what was going on when the code was written. Log actions, entry points, exit points, and parameters, and  make the code configurable. When you log from the beginning, it will be easier to pinpoint specific errors and the origins of those errors down the line.

2. Write Code that Is Easy to Modify and Enhance

To write code that is truly maintainable, it must be easy to add new functionality and features. Extensibility is vital. If a single change is liable to break the code in ten different places, then you’re in serious trouble. It is possible to make your code easier to change down the line. Here’s how.

DRY (Don’t Repeat Yourself): Many developers have a nasty habit of writing code for one purpose and then copying and pasting elsewhere to do something else. If it gets used in multiple places and there’s something  wrong with it, then you’ve just multiplied the defect. If you’re tempted to copy and paste code, consider extracting the common functionality to be available throughout your code base.

Separate concerns: You should modularize code based on distinct features that overlap as little as possible in terms of functionality. If the code needs to do fifteen things, then split it up into fifteen modules that each do one thing. Don’t try to do all fifteen things in one module because that will make it tougher to make changes without breaking everything else.

Separate code and data: You should always externalize text into separate files. For example, it takes additional effort to isolate menu options and error messages into an external file, but if you put text in the code, it will  be more difficult to change it later. Make sure you use a consistent nickname in language text file names. This approach enables text to be updated by nondevelopers without letting them near the actual code.

Avoid long statements and deep nesting: Don’t write all your code in one big function because it’s really tough to understand if it’s performing too many tasks. In my experience, a single function that is more than a couple of printed pages long is way too long and should be subdivided.

3. Write Code that Is Easy to Test

Saving the best for last, a good suite of tests can serve as documentation, indicating how the code is supposed to behave while making sure that the code actually supports the expected behavior. Even better, great tests can give you confidence that your code still works after you've made your changes.

Automated unit testing should be implemented from day one so that when you make changes, the automated testing program will run and you can see what needs to be fixed immediately. In agile, even though it takes more time at the outset to write test programs and code concurrently, comprehensive tests should save major time and resources in the long run. {end}

About the author

Kaushal Amin's picture Kaushal Amin

Kaushal Amin is Chief Technology Officer for KMS Technology, a provider of IT services across the software development lifecycle with offices in Atlanta, GA and Ho Chi Minh City, Vietnam. You may reach him at kaushalamin@kms-technology.com.

Upcoming Events

Nov 09
Nov 09
Apr 13
May 03