![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
From the IBM WebSphere Developer Technical Journal.
I met up with a colleague of mine at a wedding recently, and while discussing his current project, he started to reveal to me how some of the developers on his team were making the simplest of mistakes. While we mostly laughed about this, drinking our champagne, the sobering fact is that, as an industry, we should be way past the point where stuff like this happens. Interestingly enough, other developers on the team were quite senior, and if they had taken the opportunity to formally review the code of the junior members, they could have easily passed a bit of their knowledge -- and wisdom -- to help strengthen the team, as well as improve the quality of the final code.
It is important to realize that decisions (and indecisions) made by a team during the development process that seem sound (or even inconsequential) in the beginning phases of a project can have a significant impact as the project continues. This shouldn't be news to anyone, but I continue to be amazed by many of the problems that projects in general still face -- and especially portal projects that start out on track, but then quickly head off into a "no man's land," where assets become a jumble of incoherent and unexamined code, scattered versions of components begin to proliferate, and environments break down or go out of control.
Most of the opinions and advice that I offer, either through articles and presentations or my blog, are, by their nature, abstracted to a high level so that the ideas can be generally useful to a large audience. However, I think that practitioners often stumble somewhere between understanding the concepts and implementing them. Perhaps this is due to a lack of true understanding, or maybe there is some deep disagreement with some of the recommendations. Unfortunately, it is very difficult to give specific detailed advice to a general audience. In most cases, specific recommendations fall under the "one size does not fit all" category: what might be best for one project, may be completely wrong for another.
However, one nearly universal truth is that the best way to avoid the basic project problems that can spiral out of control is to outline best practices and guidelines for your team. In general, it is not that hard to flesh out such details. But while it does require some level of discipline to create these guidelines, it definitely requires discipline to enforce them. Doing so, however, will often result in an immediate and positive impact to your project and your environment.
What kinds of best practices and guidelines am I talking about? Well, before we get too deep into any details, it may help if you start by asking yourself these questions about your portal project or environment:
- How quickly can you diagnose problems when they occur?
- Do you know how the next version or release of your application will affect your production environment?
- Are you comfortable that new development teams understand how to create applications that will "play nice" within your environment?
- Could you be back up and running quickly after experiencing an application or backend failure?
More questions would be added to make this a more thorough evaluation, but this is enough to let me get to the point. Notice in the first question that I did not suggest finding the root cause. I think this is often a goal or mandate that management puts into place that produces more work then results. I tend to focus more on the topic of best practices and organizational discipline in cycles, even harping on it a bit until I feel that everyone has gotten the idea, and then move on to other important topics. It appears now that the cycle has come around again as a new crop of portal developers begin to build new projects.
There is no easy answer when talking about fragile portals. Governance and discipline are very important in making a positive impact. Too often, project teams look for technical solutions to these problems, and while the tooling is getting better at providing static analysis and profiling ability, there is still a level of discipline required to use them effectively. The best tools in the world are useless if no one examines or follows up on the results. Therefore, the effort required to take advantage of this tooling approach might actually be better spent performing other activities, such as visual code reviews.
When reviewing project plans, one of the major tasks is often unit testing, which is one of those things that everyone talks about doing, but in reality few people really do -- or do completely or well. When I dig a little deeper into how the team actually plans to go about performing unit testing, I often get a variety of unconvincing responses. For those of you who do not follow my blog, I have previously discussed in some detail the idea of unit testing in the portal world. Too often the conversation relegates to the line item having been put there to be a buffer in case of project overruns.
By contrast, one area that never seems to be in the project plan is the task of performing code reviews. I really like to position these in terms of a code "walkthrough" rather than the more formal sounding "review". This lessens the intimidation that the word "review" seems to bring out, without lessening its importance. Obviously, this is one of the most fundamental of project activities, yet one of the rarest of tasks that are actually performed. I often speculate that this is true for a number of reasons:
Time. Time or rather lack of time seems to be a major inhibitor of code reviews. There are some situations where reviews can be a distraction, but generally this excuse is irrelevant, considering the known impact of not performing reviews.
Skills and understanding. I think that much of the problem in not performing reviews has to do with our culture of building architects. Higher level architects might see their deeper technical skills soften, yet are still expected (or perhaps simply try to) maintain the appearance of being deep technically. A word of advice: you don't have to be an expert in everything -- nor can you. Whether or not you know how to code (and whether or not the development team knows this), you can be a true leader and help facilitate the process. Let the team do the bulk of the heavy lifting in identifying areas to streamline the code.
Developer resistance. No one likes to have their work critiqued. Hey, not even me, but it is an important part of the process. I have seen developers resist these reviews quite a bit, but sometimes forcing the issue is necessary for progress to be made. Developers, remember that this is not your code; it belongs either to the organization or to a customer. I can speak from personal experience: At one time I went out of my way to avoid reviews with one specific developer on the team who was just generally troublesome to work with. This behavior came back to haunt me as the project deadline grew near and still no usable code appeared. When I finally did force a review, I realized what a disaster the code was, and that most of it had to be rewritten.
Here's another question for you: If you could do only one thing to improve the quality of your code base, grow the skill level of your developers, and provide increased knowledge transfer of different components to new members of your teams, what would that one thing be? I gave a talk recently to a number of portal practitioners at a conference, and one of my core recommendations was the idea of code reviews. I even recommended that project managers schedule and manage the team to make sure that they occurred. Some of the audience was visibly concerned with this idea, either assuming they did not have the expertise to perform such a task, or that it wasn't their responsibility to begin with. And they are right: this challenge sits squarely on the shoulders of architects and other technical leadership, but if they cannot (or are unable to) make the effort, others should not be afraid of taking on the task.
Standards within your organization
Code reviews may not make a lot of sense unless you have standards in place to measure them against. It's no use if you spend a lot of time creating use cases and architectural decisions, but then don't lay down the basic rules for developers to follow. I recently started promoting the idea of using a Wiki to create and maintain organizational standards. I think the idea of a Wiki lends itself nicely to letting a community of people define and refine standards that can be consumed by distributed teams. In deference to the concept of code reviews, you really can't enforce standards that have not been formalized or are not readily available. IBM® itself uses Wikis quite extensively. (Although our internal intranet standards, are not in Wiki format, they are readily available to all via the Web.) For example, there are some efforts within IBM to use this approach for helping to globally define messaging standards by different groups that are creating messaging components. There is a strong need to ensure that messages are understood by different components that may be built by two (or more) totally different teams. This approach lends itself perfectly to helping make standards readily available to multiple teams and enables them to be continuously updated as needed.
The reality is that, as an industry, we have generally failed in this area. We often compare software development to other types of engineering practices, but I challenge you to name another industry that does not have a solid list of codes, standards, and inspection procedures. While some initial attempts have been made to move us in the right direction, more effort is needed. My goal is to add a new section to the Portal Patterns site that will focus on portal development standards.
This is what everyone really wants to know. What should I or shouldn't I do for my project to be successful? This is also one of the most difficult questions to answer. Remember my comment that "one size does not fit all"? There are so many general best practices, but it's in the details where things can get tricky. If I were to sum up and paraphrase the questions that many project teams usually ask me, the result would be along the lines of, "tell me everything that can possibly go wrong!" Seriously, can you expect an reliable answer to this question? And even if I were able to create a list of every potential problem, would anyone read it and follow the guidelines?
Some effort has been made to enumerate simple technical guidelines. Stefan Hepper has published several guideline articles that list specific dos and don'ts within a portal application. Tim Hanis and I have also had several discussions on this topic to try and determine how to best solidify our recommendations in ways that are directly applicable to new projects. Tim discusses many of these topics in his Portlet Development Workbook. I tend to waffle between making these decisions at a tactical level within a specific project, and making more strategic decisions across the entire organization. If a project team asks me for a direct recommendation, I may suggest using log4j or commons logging. Meanwhile, this may be in direct competition with other teams that are facing similar questions -- which later on can result in chaos. This example clearly illustrates why there is so much emphasis on making the right choices for your project and organization.
I will concede that sometimes there are technical tool-based solutions that can help many problems. In fact, I have come across some situations recently for a technical solution was sufficient. For the most part, though, this type of solution still requires some custom code to work with an organization's specific problem, actually transforming this into a services type of solution. My point here is that I realize that increased discipline is not always the total answer to solving your environment's problem's. I do believe that some discipline is required, and it's really not that difficult to enforce if the up front effort is completed.
My final bit of advice is to continue making incremental improvements as much as possible. My colleague at the wedding felt that the technical leadership of the team was reluctant to perform code reviews, either because there was not time, or becausethey were uncomfortable with their own expertise in the technology. I'll restate that this is not a reason to hold back on conducting a review; a more politically correct alternative may be to bring in a technical expert who can provide an independent code and architecture review. The goal would be to do this early enough in the development phase so that changes can still be implemented, and to repeat this at regular intervals, thereby gaining constant improvement. But even small improvements can provide a positive impact on performance, maintainability, and on you keeping your sanity during some very crazy project cycles. If you are short on time, performing this type of activity even toward the end can save you from the embarrassment and the potential cost of trying to go live anyway and not being successful.
If nothing dramatically wrong is found during the review process, you can then more forward with confidence that things will likely go on smoothly.
Oh, my parting advice to my friend? Remember, "It's supposed to be Fun!"
Learn
-
Creating a new portal, Part 5: Developing, building, and deploying the portal
-
Creating a new portal: Get your portal project started on the path to success
-
What is Wiki?
-
PortalPatterns.org
-
Best practices: Developing portlets using JSR 168 and WebSphere Portal
-
Portal Development Workbook
Discuss
Anthony (Joey) Bernal is a Sr. Consulting IT Specialist with IBM Software Services for Lotus (ISSL). Having worked with WebSphere Portal since the initial 1.1release, he has an extensive background in the design and development of portal applications, and has led the implementation of many projects using IBM WebSphere Portal. Joey is an accomplished author, speaker, and instructor in various topics concerning WebSphere Portal and related technologies. He is a co-author of the book Programming Portlets.
