Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
For someone who doesn't have much real world experience yet, the notion of maintainable code is a bit vague, even though it follows from typical good practice rules. Intuitively I can tell that code can be well written, but not maintainable if for example it hard-wires information that is subject to constant change, but I still have a hard time looking at code and deciding if it's maintainable or not.
So the question is: what hurts maintainability? What should I look for?
There are many aspects to maintainability, but IMO the most important are loose coupling and high cohesion. Essentially, when you're working with good code, you're able to make small changes here and there without having to keep the whole codebase in your head. With bad code, you would have to take more things into account: fix here, and it breaks elsewhere.
When you have 100+ kLOC of code in front of you, this is crucial. Oft-mentioned "good practice" rules like code formatting, commenting, variable naming, etc. are superficial compared to coupling/cohesion issues.
The trouble with coupling/cohesion is that it's not easy to measure or see quickly. There are some academic attempts to do that, and maybe some static code analysis tools, but not anything I know of that would immediately give a reliable estimate of how hard time you're going to have with the code.
Foo, and you call Bar on it, you can tell your IDE to find Bar and you know exactly what's going on. But if you have a more loosely coupled IFoo reference, and you call Bar on that, it can require tons of searching to find which class you're dealing with so you can look up Bar.
Feb 19, 2013 at 17:00
Duplicated code :
Copy Paste is most probably the single most expensive operation when it comes to maintenance costs of programs.
Why bother move this code to a common component, i'll just copy it over and be done with it Yes... the programmer probably saved an hour of work or so doing things this way. However later comes a bug and... yes of course it gets fixed in only half of the running code. Which means that later still a regression will be logged resulting in yet another fix OF THE SAME THING.
This one sounds obvious but in the grand scheme of things it is insidious. Programmers look good cause they get more done. Dev team manager look good cause they delivered on time. And since the problem is found only much later blame never befalls on the real culprit.
I lost count on how many times I had to halt a release because of such "regressions" Just now I lost one full day tracking a fix that was already done, get it fixed again and pushing the new build through the hoops. So yes, one hour time for one dev six months ago (approx CAD 40$) just costed one full day for 1 senior dev + half day for one junior dev + one full day delay in a project already late....
you do the math....
so next one that pulls this on me I swear he'd better run fast caus'i'll be right behind him !!!
While code which breaks the rules in the other answers is certainly worse to maintain, all code is hard to maintain, therefore the less of it you have the better. Defects correlate strongly with amount of code, so the more code you have the more bugs you have. Once code get over a certain size you can't keep your whole design in your head anymore and things get much harder. Lastly more code eventually means more engineers, which means more cost, more communication problems and more management problems.
Though keep in mind that one should not write more complex, but shorter code. The most maintainable code is simple and simply contains no redundancy to keep it as short as possible. Delegating tasks to other programs or API can also be a viable solution as long as the API calls are simple enough.
so in a nutshell, any superfluous code is a maintainability problem
Ironically, explicit attempts to "future-proof" a system often make it harder to maintain.
Not hardcoding magic numbers or strings is one thing, but take it further and you start putting logic into configuration files. Which means you're adding a parser and an interpreter for an obscure new (and probably badly-designed) programming language to your maintenance burden.
Layers of abstraction and indirection added for no other reason that some component might be changed in the future and you don't want to depend on it directly are pure maintenance poison and a prime example for YAGNI. The SLF4J FAQ explains the problems with this all-too-common idea:
Given that writing a logging wrapper does not seem that hard, some developers will be tempted to wrap SLF4J and link with it only if it is already present on the classpath, making SLF4J an optional dependency of Wombat. In addition to solving the dependency problem, the wrapper will isolate Wombat from SLF4J's API ensuring that logging in Wombat is future-proof.
On the other hand, any SLF4J-wrapper by definition depends on SLF4J. It is bound to have the same general API. If in the future a new and significantly different logging API comes along, code that uses the wrapper will be equally difficult to migrate to the new API as code that used SLF4J directly. Thus, the wrapper is not likely to future-proof your code, but to make it more complex by adding an additional indirection on top of SLF4J, which is an indirection in itself.
The last half-sentence hints at the sweet irony that SLF4J itself is a logging wrapper to which this argument applies just as well (except it's making a credible attempt to be the only wrapper you need that can sit on top of and beneath all other common Java logging APIs).
In my experience, a major factor in maintainability is consistency. Even if the program works in strange and absurd ways, it's still easier to maintain if it does it the same way everywhere. Working with code that uses different naming schemes, design patterns, algorithms etc. for similar tasks, depending on who wrote it when, is a major PITA.
I believe that code that isn't Unit Tested hurts maintainability. When code is covered by unit tests, then you can be confident that when you change it you know what you are breaking because the associated unit tests will fail.
Having unit tests along with the other suggestions here makes your code robust and you make sure you know that when you change, exactly what impacts you're having.
The only true way of learning what is maintainable code is to get involved in maintaining a large codebase (both bug fixes and feature requests).
You will learn about:
I have a couple of "nightmares" that although I'd never put them on the top of this list, they have definitely caused some struggle.
The mega object/page/function: (The so called "God Object" anti-pattern): Putting everything in one object's method (mostly Java world), page (mostly php and asp), method (mostly VB6).
I had to maintain code from a programmer who had in one php script: html code, business logic, calls to mysql all messed up. Something like:
foeach( item in sql_query("Select * from Items")) {
<a href="/go/to/item['id']">item['name']</a>
}
Relying on obscure features of the language that might not be well known or are about to become obsolete.
It had happened again with php and preset variables. Short story: for some settings of php v4 a request parameter was auto assigned to a variable. so http://mysite.com?id=42 would "magically" generate varaible $id with value '42'.
This was a maintenance nightmare not only because you could not possibly know where data came from but also because php v5 completly removed it (+1), so people trained after that version, would not even understand what was going on and why.
What makes maintainance necessary is that requirements are a moving target. I like to see code where future possible changes have been anticipated, and thought put into how to handle them if they should arise.
I have a measure of maintainability. Suppose a new requirement comes along, or a change in an existing requirement. Then the changes to the source code are implemented, along with fixing any related bugs, until the implementation is complete and correct. Now run a diff between the code base after and the code base before. If that includes documentation changes, include those in the code base. From the diff you can get a count N of how many insertions, deletions, and replacements of code were necessary to accomplish the change.
The smaller N is, as a rough average over past and future requirements changes, the more maintainable the code is. The reason is, programmers are noisy channels. They make mistakes. The more changes they have to make, the more mistakes they make, which all become bugs, and every bug is harder to find and fix than it is to make in the first place.
So I'm agreeing with the answers that say follow Don't Repeat Yourself (DRY) or what's called cookie-cutter-code.
I'm also agreeing with the movement toward domain-specific-languages (DSLs) provided they reduce N. Sometimes people assume the purpose of a DSL is to be "coder-friendly" by dealing in "high-level abstractions". That doesn't necessarily reduce N. The way to reduce N is to get into a language (which may be just things defined on top of an existing language) that map more closely onto the concepts of the problem domain.
Maintainability doesn't necessarily mean any programmer can just dive right in. The example I use from my own experience is Differential Execution. The price is a significant learning curve. The reward is an order of magnitude reduction in source code for user interface dialogs, especially those that have dynamically changing elements. Simple changes have N around 2 or 3. More complex changes have N around 5 or 6. When N is small like that, the likelihood of introducing bugs is much reduced, and it gives the impression that it "just works".
At the other extreme, I've seen code where N was typically in the range of 20-30.
I think that maintainability is also tightly coupled with problem complexity, which can be a subjective matter. I've seen situations where the sole developer was able to successfully maintain and consistently grow a large code base, but when others step into his place, it appears an unmaintainable mess -- just because they have quite different mental models.
Patterns and practices really help (see other answers for great advice). However, their abuse can lead to even more problems when the original solution is lost behind facades, adapters and unnecessary abstractions.
In general, understanding comes with experience. A great way to learn is to analyze how others have solved similar problems, trying to find strong and weak points in their implementation.
This isn't really an answer so much as a long comment (Because these answers have already been presented).
I've found that striving religiously for two factors--clean, usable interfaces and no repetition have made my code much better and over time have made me a much better programmer.
Sometimes eliminating redundant code is HARD, it forces you to come up with some tricky patterns.
I usually analyze what MUST change then make that my goal. For instance, if you are doing a GUI on a client to update a database--what do you need to add "Another" one (another control linked to the DB?) You need to add a row to the DB, and you need the position of the component, that's it.
So if that is your bare minimum, I don't see ANY code in that--you SHOULD be able to do it without touching your codebase. This is amazingly hard to attain, a few toolkits will do it (usually poorly), but it's a goal. How hard is it to get close? Not terribly. I can do it and have done it with zero code in a couple ways, one is by tagging new GUI components with the name of the table in the DB, another by creating an XML file--the XML file (or YAML if you hate XML) can be really useful because you can link validators and special actions to the field, making the pattern extremely flexible.
Also, it doesn't take more time to implement solutions correctly--by the time you've shipped most projects it's actually cheaper.
I can point out that if you rely heavily on Setters & Getters ("Bean Patterns"), Generics & Anonymous inner classes you probably AREN'T coding generically like this. In the above examples, trying to force in any of these will really screw you up. Setters & Getters force you to use code for new attributes, Generics force you to instantiate classes (which requires code) & Anonymous inner classes tend not to be easy to re-use elsewhere. If you are really coding generically, these language constructs aren't bad, but they can make it hard to visualize a pattern. For a totally nonsensical example:
user.setFirstName(screen.getFirstName());
user.setLastName(screen.getLastName());
Looks fine--not really redundant at all--at least not in a way you can fix, right? But it causes you to add a line when you want to add a "Middle Name", so it is "Redundant code"
user.getNameAttributesFrom(screen);
Does not need new code for this task--it simply requires that some attributes in "screen" are tagged with a "Name" attribute, but now we can't copy address, how about this:
user.getAttributesFrom(screen, NAME_FIELDS, ADDRESS_FIELDS);
Nicer, a var-args lets you include a group of attributes (from an enum) to gather from the screen--still you have to edit code to modify the types of attributes you want. Note that "NAME_FIELDS" is a simple enum instance--fields in "screen" are tagged with this enum when designed to put them in the correct categorie(s)--there is no conversion table.
Attribute[] attrs=new Attributes[]{NAME_FIELDS, ADDRESS_FIELDS, FRIENDS_FIELDS};
user.getAttributesFrom(screen, attrs);
Now you've got it to where you are just changing "Data". This is where I usually leave it--with the data in the code--because it's "Good enough". The next step is to externalize the data if that is ever needed, so that you can read it from a text file, but it rarely is. Refactorings "Roll up" like this a lot once you get into the habit, and what I just did there^ created a new enum and pattern that will end up rolling in many other refactorings.
Finally, note that good generic solutions to problems like this are NOT language-dependent. I've implemented a no-code-per-loc solution to parsing a text GUI from the command line of a router, updating it on the screen and writing it back to the device--in VB 3. It just takes dedication to the principle of don't write redundant code, ever--even if you have to write twice as much code to do so!
The Clean Interface (Fully Factored & doesn't allow illegal stuff to pass through) is important too. When you factor an interface between two units of code correctly, it allows you to manipulate code on either side of the interface with impunity and allows new users to implement to the interfaces cleanly.
besides the mentioned patterns one of the most important things is
readable code, every single line of code you put in a codebase will be read 100+ times and as people are tracking down bugs you do not want them spend 30 minutes to try and figure out what it does each time.
So don't try to be clever with "optimized" code unless it really is a bottleneck and then comment it and put the original readable (and working) code in comments (or alternative compilation path for testing) as a reference for what it should do.
this includes descriptive function, parameter and variable names and comments explaining WHY a certain algorithm is chosen over another
Almost everything which violates some good software development principles hurts maintainability. If you look at some code and want to assess how maintainable it is, you can choose some specific principles and check how much it violates them.
The DRY principle is a good starting point: How much information is repeated in the code? YAGNI is also very helpful: How much functionality is there which is not needed?
If you do some research on DRY and YAGNI you will find other principles, which are applicable as general software development principles. If you are using some object-oriented programming language and want to be more specific, the SOLID principles give some good guidelines for good object-oriented design.
Code which violates any of those principles tends to be less maintainable. I put an emphasis on tend here, because – generally spoken – there are situations where it is legit to (mildly) violate any kind of principle, especially if it was made for the sake of maintainability.
What also helps is to look for code smells. Take a look in Refactoring - Improving the Design of Existing Code from Martin Fowler. There you can find examples for code smells, which sharpens your sense for less maintainable code.
Too many features.
Features themselves by nature hurt maintainability because you need to write extra code to implement them, but an application without features is pointless, so we add features. However, by leaving out unnecessary features you can keep your code more maintainable.
3 and 4 are, in my experience, the most common offenders in real-life systems. Not having a proper performance/loadtesting suite makes it impossible to benchmark the impact future changes will have on performance and stability and it will cause degradation much quicker and force expensive refactorings more often. YAGNI (what's called "waste" in the Lean vocabulary) will make a system much harder to refactor and maintain as a lot of time will be wasted (pun intended) on maintaining code and backwards compatibility for features that aren't even used.
The better approach for maintainability from my experience is to have as little code as possible and shove the work to others (i.e. the software vendors) who do the maintenance for you.
I prefer to have as little custom source as possible and push as much as possible to Excel sheets, XML or property files that represent the business data and provide simple readers or use an ETL tool to do the conversion to application code.
I also try to find something that is standard based (i.e. no single vendor) if possible. However, there are some things we cannot avoid e.g. Spring for dependency injection before JEE6 and Hibernate for ORM before JEE5, log4j/commons-logging/slf4j before Java 1.4. By choosing something standard based, there is a higher possibility of switching providers especially if one becomes defunct or prohibitively expensive and you avoid classpath hassles.
Of course if you're the vendor that is providing the software that's another matter. However, if you are dealing with real life situations sometimes it's better to throw money into the problem rather than skill and time.
Anything that is not simple to understand.
The most destructive force for any kind of code is maintenance. Unfortunately, maintenance is also absolutely necessary. If the maintainer does not quickly understand the code they will either route around it which is just as destructive or almost certainly break it.
To misquote Einstein: Make it as simple as possible - but no simpler.