Writing Maintainable Code

Some very exciting and necessary discussions have broken out in the community about writing maintainable code and the different trade offs in projects. The discussion originated with Ayende's Maintainable, but for whom? post which had the section

I am okay with that. Because my view is that having the developers learn a better way to build software is much less costly than continuing to produce software that is hard to maintain. In simple terms, if you need to invest a week in your developers, you will get your investment several times over when they produce better code, easier to maintain and extend and with fewer bugs."

To which I agreed with on Its So True Post

Especially pay note to the statement: having the developers learn a better way to build software is much less costly than continuing to produce software that is hard to maintain. That's been my experience the last 18 months with our team and elsewhere. Don't punt the ball for someone else. We made that investment in our developers a year ago and it has paid for itself ten times over.

Very thoughtful comments by JDN and Frans Bouma, in both places have provided valuable discussion. I would like to take several of my comments in both places and offer them up here for a wider audience as this is a topic I am very passionate about and one that I believe our current project has achieved some significant gains in. First of all about the "perfect" world versus the "real world":

> In a perfect world, you can build a better architecture, teach people along the way, etc.

I am on a 2 million dollar large software product. I would call that the real world. A year ago, 6 out of the 8 developers had never heard of TDD, DDD, O/RM, Continuous Design, or even programmed in C#. They were used to banging out stuff in a previous version using VB6. We decided to do right from the get go. We did teach people along the way, first doing 1/2 sessions every day, where we made all the developers draw pieces of the software on the white board and taught them code smells and the like. We made it a decision that we all agreed to do everything in pairs. The two of us who were experienced made sure we paired with everyone else to teach TDD, and everything else. A year later, all 6 of them can do it, we have 2,000+ real world unit tests.

All I ever hear you saying jdn is you can't, you can't and how all of us who have worked our butt off to get here are elitist and not in the "real world." You blame everyone else. But the fact of the matter is none of us are smart, we just keep working hard on it and make it happen even when it was real tough with management. You are smart too. You are reading this stuff. You can learn it too as all of us did.

Then on whether TDD and other practices contribute to more maintainable code

Frans,

Thanks for your well expressed comments and you are absolutely right then it isn't about "technologies" but what you do INSIDE the code that will either make it less or more maintainable.

>You all miss the point. The point isn't about focusing on >technicalities: 'what's O/R mapping, what's an IoC etc.'... that's >reading some manuals and you're done. Knowing these doesn't >make the software suddenly maintainable, THAT'S the key mistake >you all make.

But IoC and things like that are PRINCIPLES, not technologies that lead to code that is able to be extended or continuously evolved without ripping up major pieces. Which O/RM one chooses may be a technology choice but O/RM in itself can and should be discussed as one of the things one can do to write cleaner code.

>The key to maintainable software is knowing why a piece of code is >written the way it is written, i.e.: why algorithm A is chosen and why >alternatives B and C are ignored, and why the feature is kept simple >and thus the design kept simple and why the design of a feature >didn't take into account some more flexibility for extension.
>A software maintainer needs answers to these questions so s/he >can make the proper decisions where (!) to make changes. This has >nothing, absolutely NOTHING to do with the usage of e.g. o/r >mapping or IoC.

I also made this comment to your comment on my blog. I am sorry if we gave you the impression that TDD was everything. It helps on the OUTSIDE but its is just ONE out of 12 practices that we follow in Extreme Programming. They have to be done together to have any benefit. We also develop the INSIDE of the code, the algorithms and such in a Continuous Design manner constantly refactoring the code looking for simplifications and making it cleaner. When we talk about this and say the code is "extensible" its not so things can be plugged in, its so the maintainers can come in and make changes 2 years later without ripping everything apart. If you don't introduce code rot into a system and you continually work against, it isn't there in the future. 18 months into our project, 2 new people came in from the outside with hardly any skill sets and although its been hard for them, they are able to look at BOTH the unit tests and the well factored code as well as pair to understand the INSIDE as well.

I hope this helps, I think this is an excellent discussion. If there is something I am not explaining well or you think I am not not considering, I am happy to talk about it. Thanks.

Frans seems to have made the claim on my blog that that TDD doesn't do anything for maintainability, or just wonders what in the world it does do for maintainability to which I said

Frans,

Thanks for your well written comments. I think, for me, its a combination of things: there is more than unit tests. There is code developed in pairs that is highly refactored. When people talk about the code being maintainable and "extensible", it's not that we have plug-ins. Its evolving the INTERNAL implementation of the code continuously and constantly refactoring it to be simple and maintainable. I do contend that the code developed this way is more maintainable and possible of future growth without ripping everything apart and starting over. Let's put it this way: I can be away from our code base for a month and with the unit tests and the well factored code, i can find whats going on in minutes.