One issue that has come to light in my current project is the lack of formal development standards. These should really be created early in the project. Before we get too deep, let me offer my definition of development standards. Stefan Hepper and Marshall Lamb have published several articles on portal development best practices, which are must reads for any portal developer or architect. However these are more in the vein of technical do's and don'ts to ensure that you write performant, well designed portal components. Development standards on the other hand are a set of softer rules that ensure an entire team stays in sync with each other and follows the same practices and conventions. These are things like
- How to use the version control system for your project
- Naming conventions for EVERYTHING! - packages, classes, variables, projects, libraries, logging, etc.
- Documentation standards for internal (in-line) and external documentation
- Exception and error handling
- Unit testing and code review processes, and code completion checklists.
There are many reasons for enforcing this type of standardization upon your developers. Working on large or even small project teams, we have all been in situations where it has been necessary to look over or even modify the code of another team member. Testing, reviewing and debugging code that does not follow any standards (or your standards) can be a daunting task, even for the best of programmers. How many times has a piece of code been scraped and rewritten for lack of understanding.
It is well recognized that for any development effort standards are important. Following well designed programming standards can result in greater consistency within the delivered code, as well as better quality, that is easier to for other developers to understand and maintain. Additional benefits of well designed and documented code reduces the cost of long-term maintenance and transition of artifacts to another team members or team. Most of the time these standards evolve with the team over time and continue to grow as new situations come up. Not having at least some standards in place before you begin, can in the best of cases cause a lot of rework as components start to come together and a realization is made that no standards are in place.
Most folks recognize the need to create standards, and will readily agree when the idea is mentioned, but committing the resources to come up with an initial set of standards is where many projects fall flat. I place this responsibility squarely on the head of the development lead. This is not saying the lead has to work overtime, rather he or she should ensure that this is a part of the project plan and that the right resources are scheduled to do this work early in the project. If you don't have the in house expertise, then hire a portal development SME for a few weeks. This might have the added benefit of teaching your developers a thing or too also! Good communication within the team can sometime mitigate the issues of no standards, but usually that is a short term solution and I found it to be a rare quality in technical leaders to be able to facilitate the type of communication needed.
As some of you know I have been a development lead on many projects, both before and using WebSphere Portal. I've actually faced this dilemma before, usually toward the end of a project, and have created a reusable template for my projects. As an added bonus for my readers, I have a development standards template that could be of use of folks who are ramping up for their first project or who don't have any current written standards in place. Admittedly this document is a few years old, but it should easily be updatable to your needs. Download the document on my personal web site here!
OK, so what's so important about these standards? Let's look at a simple example concerning logging. Unless logging is fully defined at the beginning of a project you may encounter some of the following issues.
- Each developer will use their own logging design or different frameworks
- No standardization on what should be logged or where things should be logged to
- May cause mild to severe rework for developers once things go to production and the need for standardized logging is discovered and enforced
Even if you are lucky enough to have your developers agree on a standard logging framework early in the project, there is still the issue of what to log. Everyone will agree that debug messages should be turned off in production until needed, but what constitutes a debug message vs. an error? I found the following list on-line at http://www.ganet.org/pdk/test/standards/
- fatal - Severe errors that cause premature termination. Expect these to be immediately visible on a status console.
- error - Other runtime errors or unexpected conditions. Expect these to be immediately visible on a status console.
- warn - Use of deprecated APIs, poor use of API, 'almost' errors, other runtime situations that are undesirable or unexpected, but not necessarily "wrong". Expect these to be immediately visible on a status console.
- info - Interesting runtime events (startup/shutdown). Expect these to be immediately visible on a console, so be conservative and keep to a minimum.
- debug - detailed information on flow of through the system. Expect these to be written to logs only.
I don't know if I totally agree with this list, however I have often suggested in presentations and some of my writings, that I don't really care what your standards are, rather that you had standards in the first place. As I get older and supposedly wiser that may not be as true, but until I offer a better suggestion I really can't complain. : )
So who knew such a simple thing like logging could be such a big deal? It won't be if you lay down some rules early in the project. After you have these in place, start to look at other standards such as naming conventions, and exception handling. I guarantee you will not regret it later.