Professional Scrum Master, Project Manager, IT Business Architect (JEE, Spring, ICEfaces/JSF) Author of the book "ICEfaces 1.8: Next Generation Enterprise Web Development" Rainer has posted 13 posts at DZone. You can read more from them at their website. View Full User Profile

Code Quality - Why Maintenance And Risk Management Are So Important to Developers

02.07.2008
| 10465 views |
  • submit to reddit

Is a software architect with a strong development background a kind of alien in a group of developers? Sometimes I feel like that when it comes to what I define as code quality: I program for my team members not for myself. The most important part for me here is maintenance.

Well, what is the most important part of my work as architect: risk management. So, it's important that architecture, design and the code help to get all the change and feature request in time and budget. 80% of the software lifecycle are influenced by this.

In my role as developer I can't forget about what I have to have a look at when I work as an architect. If you are a developer arguing about the necessity of Javadocs, for me the first step in risk management, you will never become a good designer or architect. I'm developing software for more than twenty years now and I can't remember how often I heard about time restrictions. No time left for this, no time left for that - for short, no time to be effective.

When there are tough milestones, I've no time left for extra communication that is a prerequisite for reuse of other members code. This thwarts their work, because of extra explanation effort, and my work to understand and use what they already compiled. So, if you think about time saving, don't think about your personal time saving, but about the projects time saving. It makes no sense if the time saving of a single developer led to extra time expenditure of three or more other project members. The number of involved people depends on the importance of the artefacts. A bad designed build process e.g. may led to 30% output losses.

It's very strange, that the most guys, I had the change to observe for some time, talking about time restrictions, were not very efficiently. Output ratio and code quality could have been better. Reasons for this I could observe: quality in self-management, communication skills, openness to experience and willingness for permanent (self-)education resp. abandonment of a comfort zone.

A developer these days has a bigger responsibility in a team of unaffiliated members. Member fluctuation e.g., in the course of the project, doesn't allow lone warriors. Every member has to think about the long run of the project, e.g. the aspects of maintenance or refactoring of her own project artefacts. What will be done with the result in the remaining 80% of maintenance? Well, for a lot of developers the first 20% of development seem to be more important - and quite a lot of them are overstrained even with these.

There are two aspects in it: designing and managing the code I write myself, to keep myself in time and budget. This I would call the developers view. And there's the reusability of my work for others, to keep the project in time and budget. That's the developers projects view, or for me in the role of an architect: risk management on a basic level.

From the architecture's point of view interfaces, components and layers are the framework for success in this context. But, that's not the point here. Even if all this has it's quality the interior of the remaining black boxes can be challenging. If a developer can't look beyond her's own nose the code inside the black box still works, but maintenance can be a real challenge. A challenge that can necessitate a re-implementation. A kind of worst case in risk management for an architect ;-).

From the developer's point of view risk management may be a kind of abstract beast. But, there are already known standards from the software development process front that are valid for, well, almost decades: code quality, design documentation, reuse. Although, there are more principles from the agile guys, these are the most important ones to me.

Code quality is a consistent application of todays Javadoc-like documentation principles. "Document during coding" is a very old principle, and still the most effective way to do this. In the moment of coding you have all the knowledge you need to create useful documentation. Weeks after this you've to invest extra time to re-analyze your code before you can document it. The result will be of lesser quality in any case.

Invest an adequate amount of time in naming conventions and interface design. Everything that has to be stable over a long period needs a consistent concept behind, that can be learned by new project members in best time. Don't forget to document this in such a way.

Even the best Javadocs can't give you the big picture behind. So, design documentation is necessary to help other project members to understand how they can extend or reuse your work. Class and sequence diagrams are the right tools to paint the concepts. Although, the Javadocs are a valuable source for interface descriptions they can't give you all contexts that you've to know for a project-wide use. A short overview of the most important interfaces and a description of the contexts they can be used in are a worthwhile contribution to the incorporation of new project members.

Reuse is still an abstract concept in the software industry. I read a lot of articles about it in the past and I think I understand the theory behind it. But, to be honest, even with the gain in experience over two decades I still fight in every project to reach my personal target mark. Maybe it's a question of tools, maybe reuse is only an illusion. Nevertheless, it's a good idea to fight for what reuse stands for: maintenance. Most of all: avoid copy-and-paste of code. Even if you need extra time to develop a concept, keep in mind: in the long run you will avoid waste of time for the project. And with the number of concepts you develop you'll become more structured in your thinking and faster in your implementation. May the design patterns be with you ;-).

A last tip, I also give to our apprentices, to get the big picture. Have a look at

Craig Larman, Applying UML and Patterns: An Introduction to Object-Oriented Analysis and Design and Iterative Development

resp. for our German readers

Craig Larman, UML 2 und Patterns angewendet - Objektorientierte Softwareentwicklung

References
Published at DZone with permission of its author, Rainer Eschen. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Pether Sorling replied on Fri, 2008/02/08 - 3:55am

To further increase the value of javadocs I can recommend using http://www.umlgraph.org/ or http://www.yworks.com/en/products_ydoc.htm both uml javadoc extensions.

Ydoc prettier output but commercial, umlgraph open source and works well enough.

Easy to configure with maven, umlgraph example below

<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.3</version>
<configuration>
<doclet>
org.umlgraph.doclet.UmlGraphDoc
</doclet>
<docletArtifact>
<groupId>gr.spinellis</groupId>
<artifactId>UmlGraph</artifactId>
<version>5.0</version>
</docletArtifact>
<additionalparam>
-inferrel -inferdep -quiet -hide java.*
-collpackages java.util.* -qualify
-postfixpackage -nodefontsize 9
-nodefontpackagesize 7
</additionalparam>
</configuration>
</plugin>

requires graphviz installed on your system..

 

Mostly Harmless replied on Fri, 2008/02/15 - 1:36pm

Larman. My favorite software development book, ever.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.