tags:

views:

1155

answers:

35

What is the single most important factor for writing maintainable code (language independent)?

+1  A: 

Good comments.

JeeBee
A: 

Documentation.

Martin
+9  A: 

Good abstraction

MattW.
There's a lot of bad, leaky abstractions out there. Perhaps one should stay away from abstractions?
Arne Evertsson
Then again, bad, leaky abstractions and good abstractions are two different things :)
Arve Systad
+22  A: 

Separation of Concerns (each method does one thing) - this stops Spaghetti code.

EDIT: (In response to Ash's comment) The key to maintainability is being able to quickly figure out what the code is doing and how to make changes in order to accomplish a task.

Having the code separated out so that each task is handled by a method dedicated to it makes this a snap.

For instance, if I want to change the way an elbow is bent on software for a robot, having a method named BendElbow makes it a no-brainer where the change needs to be made.

Carlton Jenke
Absolutely, although I find it's even better for allowing someone new to your code to quickly understand "what does what and where". When you need to make changes, orthogonality also makes changes much less tricky.
Ash
true - maintainability is all about what needs to change in order to have a certain result. Separation of concerns makes that much simpler to figure out.
Carlton Jenke
+6  A: 

Good method names

MattW.
+1  A: 

Continuous refactoring

Alan
+21  A: 

Automated unit tests.

You can slowly change the design of the code via refactoring if you've covered it with automated tests that tells you when it you are breaking existing functionality. Automated tests makes changing code less risky.

jop
I'm very much behind testing, always have been--since long before the unit testing fad became popular, however it has absolutely nothing to do with good design--Just because your code is 100% unit tested, does not imply it can be maintained.That said, unit testing should be mandatory.
Bill K
Maintainability is about making changes as painless as possible. A class that is coupled to every other class in the system is hard to test. Make it easy to test by loosening its dependencies to other classes. Designs that are easy to test are good designs. They are related.
jop
Abosolutely. Comments are extremely important but automated tests are better. Tests are like comments with baseball bats.
JaredPar
Michael Feather's definition of legacy code is code that isn't under test.
MarkJ
+5  A: 

Good upfront design. Nothing can save a poor design.

Dave
A: 

Good comments can make even the worst spaghetti code 10x easier to maintain.

Lucas Oman
The worst spaghetti code is unmaintainable.
Christopher
+4  A: 

Don't do any of this stuff! Thanks to Roedy Green for the laughs though.

cciotti
+5  A: 

Unit testing hands down. If you unit test your code from the get go then you will have a test suite that you can run to validate the validity of your code whenever you make a change.

Also, when you are writing code with unit test then the methods tend to be smaller since they are easier to test. As well, it should encourage you to make your methods to a single task - again since it is easier to test that way.

Rontologist
+36  A: 

Write it for other people to read. This means a combination of good names, good comments, and simple statements.

Once upon a time memory was scarce and cycles times were slow. programmers were encouraged to write complex single lines of code that did many things. Today memory is plentiful and cycle times are fast. You should write 5 lines of simple code people can follow instead of one line they cannot understand.

Good comments don't have to be long, but they must be helpful.

Also be consistent. Do not change styles in your code. For example don't change naming styles from one section to the next.

Jim C
The question asked for one thing. You gave 3. :P
Carlton Jenke
I always was an over achiever.
Jim C
Good point but it's not just about writing for "other people to read". Try understanding your own code a year or more later. I guess you in a years time are one of these "other people".
Ash
Actually as bad as my memory is now it looks like someone else's code after just a month or two.
Jim C
The question asked for one thing, true. In my opinion, the question is therefore badly phrased. There is no one thing. If I asked "What's the one thing that I should do to not fail in business" the only sensible answer is "avoid all the various pitfalls, such as...".
Anthony
Of course you could consider "write for other people to read" as the one reason.
Jim C
He did follow Joel's rule of asking questions for one answer each, so you can't fault him for that.
Carlton Jenke
A: 

Good comments. Good comments help with abstraction by stating the code's intended purpose, bad comments just restate what the code is doing. Comments could actually come in the form of well-designed and named unit tests.

xero
+1  A: 

Consistency.

Dan
+3  A: 

I don't think there is a single factor you can focus on. If there is I think it would have to be good judgement. Even well documented, easy to read code can be difficult to maintain if a developer used poor judgement during the design phase. No matter how good the documentation and unit test are, bad design of a production application can be almost impossible to fix.

You could also take a look at something like The Guide to Unmaintainable Code for ideas of what not to do. Informative and funny!

http://mindprod.com/jgloss/unmain.html

I have actually worked at companies that "standardized" on some of the things mentioned in there. You would think most of that stuff is just common sense, but you might be surprised.

jm4
+4  A: 

Being on 1st or 2nd level support for the software you just wrote, for a year or two after release.

Trust me, I've been there myself. The "fear" that I may have to maintain or enhance my own code in a years time is always a great motivator for improving maintainability.

Ash
+2  A: 

As I see it, the fundamental rule in writing maintainable code is that your code should be very easy to understand. This isn't as easy as it sounds, and you'll have to use all of the other techniques mentioned here to do it. It requires a certain amount of empathy because you'll have to learn how other developers see your code, and how it differs from the way you see it. A good way to get a grasp of that is to go back and look at some code you wrote a couple years ago.

Now, I suppose that it would be possible, theoretically, to write code that is very easy to understand and performs exactly the task it is intended for but which is also hard to modify in any way. I've never seen code like that, though.

PeterAllenWebb
A: 

Having good documentation. This includes code that is self-documenting (compartmentalized, descriptively named, and clear), good comments, a detailed design document that is accurate to the (most recently) final version of the code, and descriptive change notes in your source control.

If you asked for two, the second would definitely be unit tests. It was a hard choice between the two.

Jeff
+1  A: 

For me writing testable code(checkout Google testing blog) is the better maintainable code

siri
+3  A: 

There is no "single most important factor", it is a combination of several factors, as pointed out above.

Now, most of these rules can be condensed into: "write your code to read it later".
Or to paraphrase a funny yet good advice: "Write your code as if it must be maintained by an homicidal maniac knowing where you live."...

PhiLho
A: 

A consistent coding style. Things like method and variable naming conventions, styles and formats for comments, and even module/file naming.

JayG
+1  A: 

I already voted up Matt's answer "Good Abstraction" but I wanted to add something.

Documenting it's all about explaining things. I'm all in favor of Doxygen and other automatic documentation tools but crude lists of functions in an API are just better than nothing.

If you want to have your code to be maintanable, describe your solution to the proper level of abstraction and refine that level up to the code so that it's obvious what it does.

Remo.D
A: 

I'd go with some of the others, ABSTRACTION. It also helps when you understand a few software patterns, GOF is a good place to start for that kind of stuff.

Saif Khan
+2  A: 

Plenty of whitespace. - High density code is hard to comprehend. If you have more than 6 lines wihtout a blank line, then that group is probably not a cohesive thought/idea/operation.

Good variable names - explanatory, but succinct. Huge variable names are as bad as tiny ones.

Dan Hewett
+4  A: 

Read Code Complete- it covers everything about this from variable naming right through to the really big stuff and it is all necessary. There is no one thing.

My approach currently boils down to writing code to do the job that needs to be done ( not for every future job the code may need potentially to do ) using informative variable names and minimal variable scope and trying to make sure that my code needs as little supplementary documentation as possible. Sometimes this makes my variable and method names a little more verbose than they used to be ( my debugging output is very compreshensive when I use that ) but they are much easier to understand.

Maintainability is also generally an outcome of solid practice in other respects - if you are writing your code in a nice DRY way then problems are easier to find, if you've got a strong set of tests then you can see if maintenance changes are going to break anything.

Ultimately it's a question of trying to be thoughtful and writing for the future- code is only written once, after that it's all maintenance...

glenatron
+1  A: 

small, well defined functions and classes.

It's pretty easy to get used to other people's various coding conventions but if everything is in one giant class or function, my head explodes.

Jen A
+2  A: 

I would say the most important factor is DRY. glenatron Mention it already on his answer among other factors, but I think that's the most important one.

Rismo
+2  A: 

Without a doubt, writing code designed to be read by other people. This includes avoiding golf, mystery syntax, and thoughtful variable names that mean something. You can completely avoid writing any comments if the code is clean enough, IMO. \

[Picking a language with OO built in as opposed to tacked on helps too]

phreakre
A: 

I guess writing maintainable code goes beyond code. I believe it is better to understand what the requirements were (and have it documented somehow, both functional and non-functional) and then have, like, a new employee, introduced to how that turned into code.

If someone knows why code turned out to be like that, then it gets easier to make it better and / or to expand it.

For more technical things (such as an algorithm) have it abstractly explained (goal, principle) and then commenting key parts of the code and / or pattern implementations.

One thing I do also is to create mini-labs, toolboxes and code templates inside my application so that people know what is the "standard" code necessary to do one thing or to expand another (leads to some copy/pasting but helps to produce more and better).

rshimoda
+2  A: 

There is a tendency to write code thinking that the computer is your audience.

Strictly speaking, that's true since the code does have to work. But if you write with your human audience in mind, just that mindset helps to produce more readable code.

If you're worried that that will produce slow code, keep in mind that the most programs almost all of their time in very small portions of code. Start out writing for readability, then use a profiler to identify the right sections to optimise.

+1  A: 

I prefer it when people prune and shape the code as it grows. Too often you find an original spine of decent architecture with a huge cludgy mess hanging off it.

Quibblesome
A: 

Finding a good mentor. This person doesn't necessarily have to be a better coder than you, however they should be able to suggest other strategies for writing code properly. A good mentor will be to suggest many of the answers previously given to this topic. They can be a second set of eyes that let you know where your short comings are, while maintaining an encouraging, optimistic tone. They will also be flexible and constantly honing their skills as should you. That way when the next big paradigm comes up you'll be better able to separate the chaff from the wheat. This will be invaluable when Object Oriented Programming and Source Control are replaced by the next big thing (hard to imagine I know.)

A: 

Programming is performance; you should never forget who your audience is. "Code as if the person who ends up maintaining your code is a violent psychopath who knows where you live."

Kent Brewster
A: 

Strong, sensible conventions which are consistently applied. Things like conventions on where to start indexing, what end state to leave things in.

This makes it much easier to understand code, as all your code will behave in a way that is simpler.

This is at least one of my top tips.

Marcin
+1  A: 
  • Record assumptions when you make them - two days later you will be taking these assumptions for granted, but the next person who maintains your code won't necessarily make the same assumptions, and will wonder why you did what you did...

  • Code for people - the computer will do anything you tell it; code so humans can understand your code - who knows it might be you 6 months from now!

Paul Morrison