Writing Maintainable Code

Posted by Hartmut Wilms on Jun 25, 2007

Sections

Process & Practices,

Architecture & Design,

Development

Topics

Programming ,

Ruby ,

.NET ,

Java ,

Agile

Tags

Documentation ,

TDD ,

Best Practices

Sam Gentile, Oren Eini (aka Ayende), and Frans Bouma have an ongoing debate in the .NET community about how to write maintainable code, which several others have joined. The debate mainly focuses on the question, if Test-Driven-Development (TDD), O/R-Mappers (ORM), Model-View-Presenter/Controller (MVP/MVC), and other best-practices help to improve the maintainability of software.

Jdn started the debate with his thoughts on Maintainability, in which he expressed his concerns about how TDD, ORMs, and MVP/MVC might possibly hinder productivity and maintainability instead of boosting it:

One problem (well, it's really more than one).  I know for a fact that I am going to be handing this application off to other people.  I will not be maintaining it.  I know the people who I will be handing it off to, so I know their skill sets, I know generally how they like to code.

Oren Eini responded to this in his post "Maintainable, but for whom?". He agrees that it would be difficult (or even impossible) for developers unskilled in TDD, ORM, MVP/MVC to maintain a system build on theses practices and frameworks. But he thinks that keeping up bad practice in order to produce code that might be maintained by others is just a bad excuse:

Doing it the old way seams defeatist to me [...]. It is the old "we have always done it this way" approach. Sure, you can use a mule to plow a field, it works. But a tractor would do much better job, even though it require knowing how to drive first.

Sam Gentile joins the debate and agrees with Oren saying that teaching developers best practices, such as TDD, DDD, and ORM, pays off in "real world" projects, too. He summarizes the debate on his blog and responds to Frans Bourma's claim that "you can't live without proper solid documentation". According to Bouma TDD doesn't help to understand the inner workings of a software and that "there's likely a lack of in-depth design documents which illustrate WHY a piece of code was constructed that way and why for example alternative algorithm B and C were rejected. THAT is info which makes software more maintainable.". Sam Gentile responds:

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.

Frans Bouma takes the bait and counters that "it takes a lot of effort by a human to correctly parse code and fully understand what the code does. That's a mistake often made by the 'the code is the documentation'-camp". In his opinion "code can't replace your documentation: it only shows what the current implementation is, but not WHY alternatives aren't there, furthermore code is bad documentation: it doesn't show a human in the most easiest way how it works.". Oren Eini joins in again and states that he addresses this problem by "investing a lot of time coming up with intent revealing names and pushing all the infrastructure concerns down". He also responds to Bouma's argument that "documentation isn't a separate entity of the code written: it describes in a certain DSL (i.e human readable and understandable language) what the functionality is all about":

Documentation is not a DSL, and it is most certainly not understandable in many cases. Documentation can be ambiguous in the most insidious ways. The code is not another DSL, this assumes that the code and the documentation are somehow related, but the code is what actually run, so that is the authoritive  on any system.

Although the current debate very much resembles the old debate about "the code is the documentation", many new ideas and arguments have been produced that are worth pondering on. What do you think?

1. Back to top

   Writing unMaintainable Code

   by Iain Forsyth

   and old chestnut, but still valid - and funny :-)
   
   thc.org/root/phun/unmaintain.html

   Reply

2. Back to top

   "The Code Is The Documentation" is simple reality.

   by Wayne Mack

   It is not up for debate. The reality is that developers will work with the source code. For programs of any significant length, the documentation, if it ever existed, is incomplete, incorrect, lost, or simply ignored. There is no justification for writing anything less than highly understandable source code.
   
   Software libraries seem to be an area where high levels of documentation seem to be expected, but I have discovered over the years that a sample program showing at least one way of using the library correctly is far more useful than pages of documentation that leave it up to me to cobble together a working sequence. Couple the sample program with a test stub for the library and I would be more than happy to give up the written manuals.
   
   Does reading unit tests require knowledge and experience? Yes, but no more than reading UML diagrams. The advantage is that the unit tests actually validate correct operation.

   Reply

• Older >