C H A P T E R  7

Rules and Guidelines

Everyone agrees that software development standards are a good thing. Standards have tangible benefits that accrue to companies and individual developers. A standards-based company is more profitable than its disorganized competitors. Standards-based developers are more efficient; they meet their professional targets on schedule, which allows them to spend more time on the important things in life, like family, friends, and personal health.

Unfortunately, many software development shops talk about standards but never actually implement them. There are many and varied excuses as to why this is true, including these:

• Developers are not writers.
• Developers see developing standards as a huge, time-consuming project.
• Developers have higher priorities; standards development sits at priority three or four forever.
• Developers fear that standards will restrict their creativity.
• Developers fear conflict with their colleagues.

Formatting standards as terse and concise rules and guidelines is a practical way of overcoming these excuses. Developers can easily be trained to write short, active-voice sentences; this is not hard. A Rules and Guidelines document can be built in a relatively short time by adhering to Agile's core value of delivering working results on a regularly scheduled basis. A development team can make the development of rules and guidelines a realistic priority by scheduling weekly one-hour meetings that are time bound and that have an explicit agenda.

Creativity is not stifled by adhering to standards; rather, creativity is enhanced when a group of intelligent, skilled, and motivated developers brainstorm the best way to solve a problem.

Constructive conflict requires emotional maturity. Rugby and American football players start every game knowing that half the bruises they receive during the game will be inflicted by their own teammates. Software development is no different; developers will offer up solutions and ideas during a software development project and will be hurt when those ideas are rejected or altered extensively by the team. Emotional maturity allows a developer to take the hit and get on with playing the game. The bottom line is that the goal of adopting software standards is realistic and achievable.

This chapter presents a practical plan for formulating team standards by developing a Rules and Guidelines document. A cost/benefit analysis will help your team justify the effort to management. An easy-to-use format is presented as a template. Some examples are presented to help your team get its standards up and running quickly. Finally, a few words are added that discuss the tradeoff between the need for consistency and the need for change.

Why Develop a Rules and Guidelines Document?

One of the four core values of the Agile Manifesto is to value “working software over comprehensive documentation.” In all Agile areas, you must constantly remind yourself of the manifesto's caveat “while there is value in the items on the right, we value the items on the left more.” Indeed, documentation has value; you need to think about why and how to develop documentation that has significant practical value in a cost-effective manner. The term cost effective implies that the effort expended on documentation does not impair the production of high-quality working software; rather, it enhances the production of high-quality working software so the team adheres to the Agile principle of “continuous attention to technical excellence and good design.”

Benefits

Consistency is the high-level goal of using a Rules and Guidelines document. Consistency spawns many benefits that directly affect the bottom line of software development. Consistency is key to achieving the following Agile principles:

• “Working software is delivered frequently (weeks rather than months)”: Rules and guidelines define how a team codes an individual programming situation. In many cases, there are a number of ways to solve a particular problem; a rule or guideline cuts the number of ways down to one. This strategy stops programmers from continually reinventing wheels and dithering over the best way to do simple, low-value, repetitive tasks. The time savings are significant.
• “Continuous attention to technical excellence and good design”: Authoring your Rules and Guidelines document is a team sport. Chances are that, given input from multiple knowledgeable people, you will end up with some seriously practical and cost-effective rules and guidelines that result in high-quality software and practical processes that keep the team pulling together.
• “Simplicity”: Using one solution to a common problem instead of five solutions leads to simple, consistent code. Using one solution versus five solutions cuts the development, testing, and debugging times dramatically.
• End users love a consistent interface. It saves training time. It minimizes the amount of documentation they have to read. It makes them more productive because routine tasks like navigation become second nature—no more looking for the Cancel button that has been placed at various locations on an application's pages because each programmer has their own uncompromising idea regarding the button's correct position.
• “Self-organizing teams”: Authoring a Rules and Guidelines document is a positive team-building process. For new teams, authoring the Rules and Guidelines document will quickly lead them through the classic team-building steps of forming, storming, norming, and performing. Strong teams emerge from the team-building process when it is done in a spirit of cooperation, compromise, emotional maturity, and constructive conflict.
• “Regular adaptation to changing circumstances”: Refactoring code in response to changing requirements and technology is easier and much faster when a consistent strategy was applied to the code in the first place.

A practical and effective Rules and Guidelines document keeps your team pulling together in the same direction just as an eight-person rowing team coordinates each pull on their oars so their racing boat glides quickly and smoothly through the water toward the finish line. In an oared racing boat, team members put aside their own individual rowing style and conform to the team's rowing style. You can easily picture what happens when one oarsman rows at five strokes per minute and another rows at six strokes per minute; the result is a slapstick comedy. Team-based software development is no different. Each team member must put aside their individual style and agree to pull together using the team's style. A well-crafted Rules and Guidelines document is an ideal tool for defining a team's winning style.

Costs

A Rules and Guidelines document is not free. The main cost is developer time. In one project I was involved with, I measured the effort expended to develop the rules and guidelines. Here are the results:

• 4 developers
• 12 one-hour meetings over 3 months
• 2 hours per meeting to polish and format the Rules and Guidelines document
• 72 person-hours to develop the initial draft

During the first year, the team evolved and so did the rules and guidelines. The evolution was in line with Agile's principle of responding to change. The team held regular reflective learning meetings that were specifically dedicated to reviewing the rules and guidelines. Some items were added, some dropped, and some improved. The cost involved in maintaining the Rules and Guidelines document for one year worked out as follows:

• 4 developers
• 7 one-hour monthly meetings that were held after the first 3 months of initial development
• 2 hours per meeting to polish and format the Rules and Guidelines document
• 42 person-hours to evolve and improve the rules and guidelines

The total cost of the rules and guidelines in the first year was 114 person-hours. This cost reflects the formal time spent working on the rules and guidelines. There were, of course, hours spent on informal chats and debates over coffee and beer. The informal hours were not included because they were not captured by the time-entry system; however, informal time is an important part of collaboration and team building. A wise manager sets up the team environment to support both formal and informal time.

Return on Investment (ROI)

I calculated the amount of time saved by applying rules and guidelines during the first year of development and production usage of the same application that I mentioned in the preceding section. That application was constructed by four developers. Following is a summary of the time saved as a result of having a clear Rules and Guidelines document:

• Developer time saved:
  • 4 developers times
  • 5 minutes saved per working day times
  • 200 working days in a year equals
  • 67 developer-hours saved per year
• End user time saved:
  • 280 end users times
  • 1 minute saved per working day times
  • 200 working days in a year equals
  • 933 end user hours saved per year

Approximately 1,000 person-hours were saved in the first year by virtue of having a Rules and Guidelines document in place that produced an application that was consistent for both the developers and the end users.

The return on investment (ROI) in this example is 1,000 person-hours of benefit divided by 114 person-hours of cost. This yields an ROI of 877 percent. Even if the benefit estimate is overstated, it is clear that a Rules and Guidelines document makes an immediate positive contribution to your bottom line.

Audience

Who reads the Rules and Guidelines document? The development team is the obvious key user group. However, the rules and guidelines are of interest to a wider audience:

• Developers
• Auditors
• Business analysts
• Estimators
• End users

Developers are both the authors and the primary readers of their Rules and Guidelines document. Rules and guidelines are written directly for the developers and for no one else; however, other people in different roles will greatly appreciate that the rules and guidelines exist and are taken seriously.

Auditors are charged with making sure value is received for money. In a software development shop, this function can be difficult because of the complicated and often obscure nature the software environment. A Rules and Guidelines document shows the auditors that the development team spends much of its time on well-defined tasks that explicitly contribute to reaching well-defined goals. Well-defined tasks have well-defined time estimates associated with them; therefore, the auditors can, for the tasks governed by rules and guidelines, calculate value for money.

Business analysts find rules and guidelines handy when they are learning what the underlying technology can do for them and their end users. This saves time.

Estimators can take advantage of rules and guidelines by being able to associate a specific rule or guideline with a specific function point in an application. For example, if a proposed feature contains ten lookup tables, and a guideline standardizes the method of building the maintenance pages and related lists of values, then it is a simple matter of multiplying the guideline estimate by ten and adding the result to the overall estimate for the feature. This method is not a panacea for making good estimates; rather, it is a quick way to efficiently quantify much of the routine work associated with software development. Quickly accounting for the routine stuff frees the estimator's time so that more effort is available for the difficult areas to be estimated.

End users will probably never directly see or read the Rules and Guidelines document. However, they indirectly see and experience the benefits when they are presented with a suite of applications that has a consistent style, look and feel, and architecture. A good example is Microsoft Office: users can switch back and forth between the product's various modules and find that common elements like file management and printing are found in the same place and are named identically. Consistency like this makes the end user productive.

Structure

The following structure for a Rules and Guidelines document is simple and effective:

• Table of contents
• Environment
• Principles
• Rules
• Guidelines

Table of Contents

A table of contents is useful for any technical document. Readers can jump straight to the part that they need; this saves time. It is always surprising to me when I find in-house documentation that lacks this helpful and easy-to-create feature.

Most of us think of a table of contents in the context of a traditional document authored in a word processor. In today's world, I strongly recommend that you use an online tool to author your rules and guidelines. Websheets, a marquee feature of APEX 4.0, is an ideal tool for this purpose. The table of contents in this environment becomes a list of links on a home page.

Environment

A brief description of your overall environment helps to keep your rules and guidelines within reasonable boundaries. Your environment is the context that guides decisions of how to deliver software solutions to your customers. A typical environment might be described as follows:

• We are an oracle shop with 20 developers.
• We have 15 senior developers and 5 junior developers.
• Our main tools are Oracle Forms and Oracle Application Express (APEX).
• Over time, we will migrate Oracle Forms to either APEX or ADF, or perhaps a mixture of both.
• We have approximately 2,000 end users scattered throughout approximately 93 departments.
• We publish company information on an external web site.

• Team technical skills:
  • Oracle Forms—Expert
  • Oracle Portal—Expert
  • PL/SQL—Expert
  • SQL—Expert
  • APEX—Proficient
  • BI Publisher—Proficient
  • JavaScript—Novice
  • ADF—Novice
  • AJAX—No knowledge
  • jQuery—No knowledge

It is important to be honest in describing your environment. The environmental description will guide you as you develop your principles, rules, and guidelines. It will also guide you as you look to the longer term and will influence your future training plans and technology acquisitions.

Principles

A clear and articulate statement of your team's principles together with the reasoning behind the principles helps you to proactively manage your customers' expectations. For example, you might adapt the agile principle of simplicity and create a more specific version of that principle for your current project:

We will minimize the work done and the client's costs by not expending effort on code to support features that we believe the client might possibly request some day, but that are not currently in the requirements for the project.

The goal here would be to apply the Agile principle of simplicity specifically to the issue of whether you create hooks now for nice-to-have features that might or might not be requested years down the road.

Your client's expectations are often formed by a small number of sophisticated applications that have been developed over many years at the cost of hundreds of millions of dollars. Most companies, even large ones, cannot match the software-development budgets of Oracle and Microsoft. Your statement of principles enables you to negotiate from a position of strength when clients come to you with requests and suggestions that would pull you away from your efficient and cost-effective way of developing software.

Rules

Rules are to be followed 100 percent of the time with no exceptions; therefore, the rules section of your Rules and Guidelines document should be very short. Many developers do not like to be forced into a box; however, when the reasons for the rules are clear and are clearly beneficial, most developers are happy to conform—at least, that has been my experience, with only a very few exceptions.

The specific rules that govern a team are unique to each team; much depends on the team's environment. Candidate topics for rules could be

• Naming conventions for Oracle database objects
• APEX item validations
• Error handling
• Code instrumentation
• Using APEX lists for navigation instead of APEX tabs
• Authentication
• Authorization
• Page security

Keep the long-term ROI in mind when authoring your rules. A rule must deliver high value throughout the entire software life cycle.

Guidelines

Guidelines are to be followed approximately 90 percent of the time. Most well-engineered software takes advantage of patterns, and most situations fit neatly into these patterns. Like rules, guidelines keep programmers productive and the software consistent. Most of the time, programmers will apply the guidelines to their work in exactly the same manner as the rules.

Adopting guidelines in a team environment requires compromise, which, in turn requires emotional maturity on the part of team members. Seemingly trivial group decisions can cause a great deal of potential conflict. I worked in one shop where the number of indentation spaces in code was a major bone of contention. This illustrates the fact that some developers can have very strong opinions and can be very passionate about how to do things the “right” way. A passion for excellence is a good thing, but it must be tempered by a healthy dose of pragmatism and at times, uncomfortable compromise.

Every team will come up with its own unique set of guidelines. Here are a few examples. APEX offers many choices when creating a validation on an item. A guideline could limit the number of choices when selecting a PL/SQL validation. The guideline could recommend using the “Function Returning Boolean” option and ignore other three options. A guideline could recommend using the “Reports Region 100% Width” template for all report and forms regions. A guideline could recommend horizontal list regions for tab-like navigation across the top of a set of pages replacing the need for APEX tabs. A guideline could recommend the preferred way to trap and report PL/SQL errors in an APEX PL/SQL autonomous block. The number of possible guidelines is infinite; teams must choose wisely and not micro manage trivial parts of their software development environment. Good judgement in this area is mandatory and it is always good to remember the Agile prinicple of "simplicity".

Exceptions always exist. They must be brought up in the team's daily meeting. The team must throw ideas around to see if the exception can be restated so it fits into the guideline framework. When the exception is accepted as a true exception, then the team brainstorms a solution. The solution is coded together with the appropriate level of comments. Commenting the exceptions is always mandatory—in other words, doing so is a rule.

Publication

I strongly recommend the following suggestions for publishing individual rules and guidelines:

• Use one page per rule or guideline.
• Use standard headings.
• Use short, terse, concise, active-voice sentences.
• Use screenshots generously.
• Use APEX's Websheet tools to author a web-based document in a Wiki format.

Having one rule or guideline per page makes the document modular. This strategy makes it relatively easy to adapt the rules and guidelines to individual projects through a mix-and-match process. Advocates of the Pragmatic Programming methodology will find this approach attractive because it allows teams to quickly pick the rules and guidelines that suit individual projects.

Standard headings provide a template. Templates speed up the writing process by providing a consistent framework and pattern.

Short, terse, concise, active-voice sentences are easy to write, easy to read, generally unambiguous, and use fewer words that their passive voice cousins.

Screenshots are valuable. They save a lot of writing and, in many cases, can completely replace writing when they are accompanied by terse annotations.

Publishing rules and guidelines in an APEX Websheet makes a great deal of sense when the team works almost exclusively in an APEX environment. The benefits of using a websheet are as follows:

• There is one master copy. Old, out-of-date copies do not exist.
• Websheets can be maintained by multiple authors. This is attractive in an APEX environment where multiple diverse technologies are used simultaneously. The team's technology experts can take charge of their area of expertise. The team should appoint a moderator to oversee the websheet so that consistency and clarity is maintained over the entire Rules and Guidelines document.
• Websheets are APEX centric. Therefore, the environment is already familiar to the team. The learning curve for websheets is very shallow.
• All developers can quickly and easily access the rules and guidelines websheet from within their APEX development environment by using the Links region on the Team Development home page (see Figure 7-1).

Figure 7-1. Team Development link to the Rules and Guidelines websheet

Format of Individual Rules and Guidelines

Headings for individual rules and guidelines are divided into mandatory and optional sections. At least one of the optional headings is always present. The headings are as follows:

• Mandatory section
  • Title
  • Rule or guideline
  • Why
• Optional section (one optional heading is usually present)
  • Result
  • How
  • Notes
  • See Also

The Title heading contains a single word or simple phrase that describes the rule or guideline. Use this as the navigation link to the rule or guideline in a websheet. Use it as a table-of-contents entry in a conventional word-processor document.

The Rule or Guideline heading contains a simple, active-voice statement that describes the main purpose of the rule or guideline.

The Why heading can be one word: “Consistency,” for example. Some rules and guidelines will, of course, require more justification. The Why heading is important for developer buy-in. It's also an important negotiating tool used when other stakeholders challenge the team's strategies. Most of your stakeholders are reasonable. You can win them over to your vision by presenting them with logical reasoning that has validity in the short and long terms.

The Result heading often contains nothing but a screenshot of the desired result. This is frequently all a developer needs. For example, experienced APEX developers know exactly how to build a horizontal navigation list that is based on images. The guideline does not need to tell them how.

The How heading is used where you need to document the details of how a result is to be achieved. You do this when

• There are multiple ways of getting to the result.
• Multiple steps are required.
• You have programmers who are not yet proficient using APEX.
• You need succession planning for periods of high programmer turn over.
• You share resources with other teams, and programmers are assigned to you for short periods of time.

The How heading is the logical place to publish code snippets that can easily be copied to the working code. This is a great time saver.

The Notes heading is used to document aspects of the rule or guideline that are not obvious. Some guidelines may have side effects. Perhaps a guideline is an imperfect solution based on a technical compromise. This heading saves time by alerting programmers to the circumstance before they waste effort solving a tricky problem that has already been explored and dealt with.

The See Also heading points developers to related rules and guidelines.

Figures 7-2, 7-3, and 7-4 illustrate how a Rules and Guidelines document looks when it has been published using APEX's Websheet tool.

Figure 7-2. Rules and Guidelines websheet with a table of contents on the home page

Figure 7-3. Rules and Guidelines websheet drilling down into rules

Figure 7-4. Rules and Guidelines: a sample rule in a websheet

Consistency vs. Change: Refactoring

Consistency conflicts with change. Rules and guidelines tend to favor consistency during development. Yet Agile calls for being receptive to change. How do you resolve that apparent conflict in an Agile context? The key is timing.

Consistency

Consistency provides significant value within a project. Consistency is a major factor in your ability to deliver a quality software product on time and within budget. In this context, consistency directly supports the Agile principle “Working software is delivered frequently (weeks rather than months).”

Staying with a devil you know is generally a low-risk option when you are under the gun to hit hard deadline and budget targets. Change, in this context, can be extremely risky.

Change

Change provides significant value when it improves quality, shortens delivery times, and lowers cost. Change directly supports the Agile principle “Regular adaptation to changing circumstances.”

Change is risky. Change pulls your team out of its comfort zone. However, adopting change is the only way to improve. It is the only way to avoid repeating mistakes over and over again.

How does a team embrace change? Here are a few suggestions:

• Hold end-of-project reflective learning meetings. This is a core feature of the SCRUM Agile methodology.
• Budget time for research. Give programmers explicit time blocks where they concentrate on pure research for the team. Do not mix research and production time; doing so will harm both efforts.
• Research tasks must produce a tangible result. This is usually a bit of working software that demonstrates why and how a new idea can be adopted. Rejecting an idea is also a valid outcome of research.
• Start using your new tool or process at the beginning of a new project. This gives the team time to get comfortable with the change before the end-of-project crunch time adds pressure.

Refactoring

Refactoring existing code directly supports the Agile principle “Continuous attention to technical excellence and good design.”

Refactoring is done only when the benefits far outweigh the costs and risk. A sub-optimal rule or guideline is acceptable when the value of consistency trumps an optimal solution whose benefit is marginal.

Refactor your existing code aggressively. Anything less will leave you with a mix of old and new ways of doing things, which defeats the pursuit of consistency. Aggressive refactoring is done by treating the refactoring task seriously and attacking it as an all-or-nothing project. Partial refactoring leads to an inconsistent environment that increases your costs and causes your users to be frustrated and to lose confidence in your ability to produce reliable and easy-to-use software.

Summary

Standards are a good thing. Think about this the next time you plug in your laptop. The power cord and the plug in the wall are a beautiful examples of standards in action.

A Rules and Guidelines document is a cost-effective and efficient template that helps a software development shop to implement standards-based software development practices. Standards-based software development produces consistent software products that make developers, testers, business analysts, and end users more efficient.

Standards-based software development directly supports the goals of the Agile Manifesto and its Twelve Principles. Standards enable teams to produce high-quality working software within short scheduled time frames. Standards-based software is easier to refactor when the time comes to adopt the inevitable changes associated the rapid pace of software evolution.

I hope that you use this chapter to get started down your team's unique road to standards-based software development within an APEX and Agile framework.