BW's IT Blog

SOA: Requirements and Architecture

2011-03-28T00:55:00.001-07:00

In the past 5 years, SOA has made enormous leaps and bounds. Some organizations swear by it, others swear at it. But one thing is for certain... CIO's love it.
Why? Because SOA makes the business feel like they are in control.

What is less understood, is that SOA, like its predecessors (COA, OOA and POA), is still Architecture, which puts its application in the hands of technical, and not business people. What SOA does provide is a simplified way of business people and technical people to talk to each other. This talk happens in terms of:

Business Process
Services

Business Process
One of the architects that puts this brilliantly is Brian Petrini. In all his seminars that I attended he made it a point to say that an SOA should always first be described in terms of the "current process" and then later refined to a "better process".

My own definition of a business process is: "A business process is a set of steps/actions undertaken by one or more business units that has a specific business outcome."

As such it is my opinion that only a business person can define a business process.
Business tasks are also in the realm of a business person.
In essence: The business process and all the steps/actions that it entails are within the domain of "The Business".

This brings us to a clean outcome... namely that "The Business is responsible for defining the Business Process".

In many an occasion I have found that The Business misunderstands this to be "The business is responsible for Automation of the Business Process" just as many times as I have seen technologists believing that "Technology is responsible for defining the Business Process".
To be truthful, both automation and definition of Business Process may influence (but only influence) each other.

Business Service
I define a Business Service as: "A set of repeatable (and related) Business Tasks that are performed by a (single) Business Unit that attribute to a know Business Outcome for which that Business Unit is responsible".
As you see, the description of a Business Service is almost identical to the one of the Business Process with the following
exceptions:

A Business Process is not necessarily performed by a single Business Unit, but may consist of "collaboration between" different Business Units.
A Business Process has a specific Business Outcome, just like a Service, but that outcome is not restricted to be the responsibility of a single Business Unit.

In fact, these small differences make it possible for me to assert that a Business Process is a special Business Service that has the whole business as the responsible provider of the service (rather than just a single Business Unit). A Business Process generates overall outcome, whereas a Business Service generates specific outcome.

For example:
The business process defined for an insurance claim, aims to provide the single outcome of a processed claim (which is either paid out or declined).
The business process of a money transfer provides the single outcome of a completed transfer (either credited and then debited or rejected in its simplest form)

However, many business services may have been involved... For example
The claims process involved a Fraud Check (provided by legal services), a damage report (provided by valuation) etc...
A money transfer process involved a Disposition Check (by Accounts) and a Transfer Route Calculation (by Interbank Transfer) etc...

As you see, even though each service has a specific outcome, there is no holistic process outcome (no end-to-end result). The process however did have an end result.

So what does Architecture have to do with all this?
This brings me back to the "who is responsible for what" question that Business and IT sometimes get entangled in.
Most of the time the Business wants to ship a product fast or change their strategy in an ad-hoc fashion. Being the owners of the Business Process and the Business Services, they want to dictate "HOW" these changes should be made and this is the problem. Changing a Business Process is not the same as changing an automated Business Process. Implementing a Business Process is not the same as implementing an Automated Business Process.

So how is this different?
This is different because of Service Level Agreements and Key Performance Objectives

Both of these points have a Business, as well as a technical impact.
The choice on how to implement a Business Service may have far reaching repercussions on the key architectural markers (Architectural KPI) e.g.:

Availability | The way in which a process is automated may affect availability e.g. during system upgrades or maintenance or when the system is under load.
Performance | The way in which the process is automated may affect performance e.g. when the system is under load or the hardware environment is not up to spec.
Reliability | The way in which the process is automated may work well if all the components/services are in operation, but what happens if one part fails?
Scalability | The way in which the process is automated may not allow the system to scale if its use increases.
Cohesion | The way in which the process is automated may be such that services are tightly coupled, which makes everything fail if only one thing fails.
Complexity | The process or its services may be defined in too complex a way for these to be adjusted or maintained.

There are many more of these markers that influence the overall outcome, but they all lead to any the following being affected:

Resources | People or Money
Time | Time to Market/Time to Adjust

They i.e. affect the main reason for SOA: Management of TCO/TCA.

Architecture (and to a degree Development and Infrastructure), i.e. Technology Specialists are the ones who (should) understand technology and implications of technology choices. This takes many years of training and experience. Computer Architecture, Database capabilities (indexing and partitioning), network bandwith, compression, search algorithms, caching, queuing mechanisms, webservice complexities etc... etc... are things that Business People do not understand well enough to be able to understand the implications it may have to Architecture markers. It is therefore of vital importance that The Business describes their requirement (the what) and not the solution (the how), because no matter how simple it may seem... the underlying technology is still technology. We still deal with processors, memory, disk and network... In fact over the years these have become more and more complex (diverse) due to the
introduction of mobile computing, wireless networking, solid state storage devices etc... etc...)

SOA, Requirements and Architecture
So, what does this mean for requirements and architecture?
The business should describe:

The information.
Each step of processing the information (i.e. the order).
What happens as part of processing the information (what changes).
Who/what may access the information (and in which way... read, update, remove)?
How long do we expect each step to take?
How long do we expect the process to take?
When should the system be accessible?

Technology should describe:

How the information is stored (information storage... do we use a database?).
How the information is transmitted (information format/exchange... will we use XML?).
How each step will be interconnected (process definition implementation... are we going to use BPEL).
How the information is changed (information processing implementation... will we use a business rules engine? do we use web forms?).
How the system will make sure that the information is accessible according to definition (security... do we use single sign-on?).
How the system will perform (performance... will we use caching? will we use compression?).
How we meet system accessibility (scalability, reliability, availability... do we use HA? do we need failover? disaster recovery?).
How do we make sure that IT professionals can be efficient in changing the system (homogeneity, cohesion, complexity... will we use pointers? how will we name variables? do we deploy on Linux)?.

The next 10 years will define how we adequately define the responsibilities of "The Business" and "Technology". SOA has taken us a step ahead. SOA Governance is only the cap of the iceberg. We need to further define what "ownership of technology means"... After all, how many business people fix their own car after a crash or decide to architect their own highrise? And how many technologists are brave enough to borrow millionsin one place and invest them in another? Like shortcuts in business principle and risk assessment, shortcuts and unsound technology decisions can cost a lot of money (infact it is costing us billions every year). Let those who know what they are talking about do what they have to do.

Service Interfaces

2009-11-04T00:27:00.001-08:00

Lately I have found myself in discussions about "Service Interfaces" again.
Based on these discussions I have found that there is still tension between service providers and consumers about interface size.
Regarding this issue, there are two schools of thought:

In the GCD (Greatest Common Denominator) school of thought, the service interface has to encompass every item of business information in its model. The full model is used as a vessel between consumer and provider. All information items on the model are considered optional and each Business Service "picks" the items that are of interest to it.

The problem with the GCD model is that every service provider and service consumer NEEDS TO BE AWARE of the full business model as a whole, even though they may only use a fraction of the model.

In the LCD (Least Common Denominator) school of thought, the service interface contains only the items of information REQUIRED to fulfill the service. Each Service has its own vessel of information interchange, that is passed between consumer and provider. The physical interface contract is strict. This facilitates that most of the semantic validation of the interface is enforced syntactically.

I found that adversaries of the LCD approach fear that soft-semantic changes to the service requires change to the interface.
This statement may not necessarily be correct.

The key lies in "separation of concerns". To be more precise, the separation of "Service" concern and "Data Management" concern.
Consumers are primarily interested in Services and concerned about "Service Integrity". Providers are traditionally concerned about "Data Integrity". Service Integrity and Data Integrity are not always the same thing, even though they are often heavily influenced by one-another.

Service Integrity strives for predictable behavior of services.
Data Integrity strives for consistency of information.
A Service provided by a system that has data integrity problems tends to behave unpredictable.

If the concerns of data management and service integrity are separated in the service interface, the service consumers will be issued with a LCD type interface into a course grained service. Additional information required by the service providers (but not the service consumers) is acquired by the provider through "choreography".
This approach includes the following steps

The consumer provides the information that it needs to know in order to use the service.
Choreography is used to aggregate the information provided by the consumer with other pieces of information required by the service providers. This could entail the use of ancillary services.
Providers process the aggregate information.
The service returns ONLY the information that pertains to it.

In the Policing domain, updating charge information would not require all the information regarding a Person of Interest including their criminal history etc... Typically a Charge Service would need a Person of Interest artifact and a Charge Artifact. The Person of Interest artifact could consist of only a reference number (integrity concern), name and date of birth (client concern) so that both service and end-user can make an accurate decision of adding a charge. The implementation of the Charge Service itself (rather than the service consumer) could then orchestrate the charge update in such a manner that Case Information, Criminal Activity statistics and such are appropriately maintained (data integrity).

LCD based interfaces do not necessarily have to be disjunct from a CIM (corporate information model). Items that make up the request can (and should) still use types that are defined in the CIM. This is precisely why a CIM must be carefully crafted.

The 3-way model for CIM model elements generally serves well.
This 3-way model provides each entity in a CIM to have:

a "reference representation". The "reference representation" only includes a system based identifier and a human based identifier (where required).
a "full representation". The "full representation" contains every element that makes up the entity with ALL elements that are required for data integrity purposes (from the perspective of the corporate model) set to "required"
a "loose representation". The "loose representation" contains every element that makes up the entity with ONLY the system based identifier set to required.

"Reference representations" are generally only used by services that require the indication of dependency with non-service parts of the model. "Loose representations" are used by services that primarily require information for display purpose. "Full representations" are generally only used by the service providers and within the service itself.

The Stories that make a Service

2009-09-07T00:03:00.001-07:00

I have been a supporter of Agile Software Development for many years now. The simplicity of Agile principles and practices, for me, provide an excellent framework for timely delivery of code.

Until fairly recently, application of Agile in IT, to me, has only been applicable in the area of Application software development. This is because I used to see Agile’s “Develop only what you need right now… Test first… Refactor to eliminate waste… Release often” to be extremely difficult to apply in an Enterprise context because:

It was hard for me as a “techie”, to predict changes to a system of components that underpin a business process.
Building only for “what is needed right now” can be extremely complex, when what one system needs right now, is not necessarily what all the other systems in the complete applications landscape need “right now”
Refactoring components in a complex system of autonomous, heterogeneous parts has significant risk to the system as a whole

There have been other reasons why I was reluctant to apply Agile across the Enterprise, but none matter anymore since I understood the real benefits of SOA.

Which brings me to the title of this blog “The Stories that make a Service”

To be truthful, of all the Agile approaches that I have really followed, XP is the only one that I have used in practice fully.

In XP user requirements are defined as “User Stories”.

As such “User Stories”, to which I will further refer to as “Stories”, are the building blocks for systems developed using XP.

For the purpose of this exercise, it is important to understand that I see an information system as a giant ensemble of Consumers and Producers of Information.

What brings Consumers and Producers together in an SOA are: Services.

A Service delivers the information required by Consumers from information provided by Producers.

Often, in order to be able to provide the information “as required” by the consumers, the information provided by the Producers needs to be “massaged” (which can mean… aggregated, transformed, or processed into derivations). It is for this reason that in an SOA, the Consumers do not obtain information from the Producers directly, but from Providers instead.

With this breakdown in Consumers, Providers and Producers, applying XP (and I believe most other Agile methodologies) has become easy.

This article explains why.

In order to understand how Stories, through the Consumer-Provider-Producer paradigm, suddenly become applicable across the Enterprise, it is important to generally make these acronyms more concrete.

An Application (i.e. a piece of software that a user interacts with) is generally seen as a consumer. There are other types of consumers, but Applications are easy to understand.

A Data Source (or Repository) is generally seen as a producer. Please note that I see a Data Source to be anything that provides data (a file, a database, a business rules engine...).

Services are in an SOA deemed the Providers. Services provide their Consumers with the ability to manage (create, retrieve, update and delete) information that is maintained by Data Sources.

Just as functionality within an Application can be described by its users using Stories, Services can be described by business representatives using Stories.

Instead of each Story describing part of the process of using an Application, in the SOA a Story will mainly describe a part of the Business Process within the Enterprise.

Because, in using SOA there is no translation required from Business Requirements to IT Components, each (technically) delivering part of the Business Process, but rather, the Business Process is defined as a ensemble of Services, the Story paradigm can effectively be put to work.

The principle being: “The Business, understands their Business Process best and is therefore the most capable of describing the Business Process in terms of Business Tasks and group these Business Tasks together in a way that they make business sense in terms of the business process”.

If a Story represents the afore mentioned grouping of Tasks, each story then represents a Service.

The beauty of it is that:

Consumers (mostly applications) can be defined in Stories
Providers (services) can be defined in Stories
Producers (almost always within the “techie” domain) can be defined in Stories

Stories can be estimated, a Velocity can be determined and in every case, there is traceability from both Business and Technical perspective, thereby solving the problems mentioned at the beginning of this article so that:

It is no longer hard for me as a “techie” to predict changes to a system of components that underpin a business process, because these components (i.e. Services) already represent groupings of Business Tasks that make up the Services that again make up the Business Process.
Building only for “what is needed right now” is no longer complex, when what one system needs right now, because these systems are built on Services that underpin the Business Process for the complete applications landscape as it is “right now”
Refactoring components, now defined and interfaced as Services in an environment that is built on these Services is now isolated on a per Service basis and will predictably affect the entire process (and therefore predictably affect each Application that “participates” in that process).

Of course it should be understood that SOA is not a magic bullet for Agile to work. SOA still requires solid Governance practices to ensure that changes in Business Process, Supporting Applications, Services, Data Sources and Infrastructure continue to be able to meet the Business' competitive needs.

Enterprise Architecture?

2008-11-27T14:57:00.001-08:00

Now the reason why there is a question mark at the end, is not because I don't think Enterprise Architecture is not a worthy field in the IT landscape. The reason I am writing this article is to "vent my spleen" on the way that organizations "apply" Enterprise Architecture (or at least what they advocate as Enterprise Architecture). And, yes I know there is a maturity model, but I do expect that as soon as organizations start introducing an EA, they will steadily climb up the ladder of EA maturity.

Now I'm not sure that it is the "resistance of the organization" or the "incompetence of enterprise architects", both or just due to the fact that "EA is too hard to apply" in most organizations. I can't judge the truth of this matter, because I am not an Enterprise Architect (although it is my ambition to once fill that role), nor did the management of the organizations that I have worked in to date explained their "EA goals" to me (or my fellow "staff").

What I have found organizations call EA, is generally a whole lot of "Hot Air" and "No Substance".
Expressions such as:
- We are aligning IT to the Business
- We are establishing governance
- We are trying to get high ROI
do NOT convince me that there is an EA.

Usually, when I ask for at least an outline or a high level excerpt of the EA, I am told, that this cannot be dissiminated due to "high confidentiality". This really makes me wonder how an organization can achieve their "strategic IT direction" without disclosing to the people who will make it happen, what that direction IS. Frankly, it is like the captain NOT giving the crue any idea where they are going, but expect them to brief the passengers on this very same topic.
"Ladies and Gentlemen, this is your purser speaking... We welcome you to our flight to... well, don't know that yet, but the captain knows..."

I believe that if the strategic IT direction contains Business Secrets, than it cannot be the IT direction... frankly, it cannot even be a Business Direction.

Funnily enough, many (unfortunately not all) organizations that I have worked in, thoroughly cover the Strategic Business Direction. This makes me wonder even more how it becomes impossible to even outline a high level Strategic IT Direction as general IT Strategic Goals and Guidelines to achieve the Strategic Business Direction that is well known.

I have even seen an organization, where on my question where the Enterprise Architecture was documented so that I could make my Solution in line with it, the Enterprise Architect (yes you have read it correctly, not an IT Manager or a Project Manager or some other Manager, but the Enterprise Architect) handed me a tabulized list (a 1 pager) with technologies that were approved.

Now... how scary is that?

To this end, as an Application Architect, I am writing this blog, backed by my understanding of what an Enterprise Architecture should entail, so that the professionals that need to REALIZE the EA, know exactly how to define, build and implement their solutions.

1. A Mission Statement
An Enterprise Architecture MUST have a mission statement. This is a very short excerpt that summarizes the Strategic Business Direction, and outlines which type of IT solutions will be key to achieving this direction

2. An Architecture Landscape
A Graphical representation of all the high level IT components (i.e. applications running in networks on hardware) and their inter-relationships that make up the IT infrastructure. This graphical representation should be accompanied by a tabular data-dictionary that map each system to a set of Strategic Business Goals and highlight the level of importance in achieving the related goal

3. A "Gap Analysis"
An analisys of which Strategic Business Goals supporting components have been fully realized by IT, which ones have been partially realized, and which ones are yet to be realized.

4. A "Grand Plan"
That outlines which existing components will be reused, which components will need to be obtained (purchased or built) in order to achieve maximum capitalization on the Strategic Business Direction with the highest level of ROI possible in an agile way so that it can suit the "ever changing needs of the business".

5 A "Technology Plan"
A list of technologies that will be used within the organization in order to achieve the "Grand Plan", as well as a process for deprecation of existing technology and introduction of new technology (be it either hardware or software)

6 A "Tracability Matrix"
This would be a glorified checklist that identifies the Strategic Business Goals in association with the Strategic IT direction and how progress to meet these Strategic directives can be measured.

It is important that from a "high level", ALL IT STAFF, ALL MIDDLE and SENIOR MANAGEMENT and KEY BUSINESS STAKEHOLDERS are aware of the Enterprise Architecture.

I also believe that the road to a mature EA starts with:
- Understanding Strategic Business Needs
- Creating Strategic IT Awareness

Well, those were my 2 cents worth...

Code Reviews

2008-05-28T19:00:00.001-07:00

Thought it would be good to include this article from my other blog (Brian Welch's TechBlog). Njoy!!!

A while back, my organization introduced code reviews...
I wanted to take the opportunity today to provide you with a snippet of the particular points of note while reviewing code (and why this is useful). The snippet is part of an e-mail I sent out to my fellow team members when we were initially establishing our code review process (in 2005). These principles still apply when reviewing code... so here goes:

Code Reviews
Code reviews are put in place to as a last quality check of the code before it goes into the released system.
Quality of code means:

Is the code in line with the detailed design and the existing architecture?
Does the code adhere to the coding standards provided?
Is the code self explanitory (naming and structuring are key here)?
Does the code attempt to solve problems that were solved elsewhere (i.e. were design patterns applied to solve common problems)?
Does the code attempt to solve problems in a way that is known to cause other issues (i.e. were anti-patterns avoided)?
Where the naming is not sufficient to describe the code, is proper API documentation provided?
Are useless comments cluttering the code? (e.g. rewording of a something that is already explained by a name)
Are the corner cases in the code well guarded (Exception handling)
Do the unit tests test the main functionality provided by the developed unit?

Is the code in line with the detailed design and the existing architecture?
Generally, developed software applications are existing production systems that are in line with an existing architecture and technical design. These systems are supported by a production support team, that needs to be able to quickly respond to defects in systems, as well as develop enhancements requested by the business stakeholders. Changes to the architecture or technical design, slow the production support developers down in providing these changes timely, as there is a learning curve involved and the production support team is generally on a very tight (forthnightly) release schedule. Any change to the architecture or to the technical design of these systems must be approved by the Application Architect (in collaboration with the senior developers in your team).

Does the code adhere to the coding standards provided?
Coding standards may at time seem limiting in coding freedom, or may (when first adopting) slow a developer down a bit. Mostly, the reason not to have coding standards is: "It's too hard to think about trivialities such as formatting, naming and API documentation... "The logic is more important". Sadly, this is not really true... having consistently formatted code makes reading the code easier for everyone (not just the person who did the coding, but also for persons having to maintain the code afterwards). Most of the formatting can be done by IDE templates or special programs (e.g. XML-tidy or Checkstyle). However, the discipline comes into the picture when checking the code back into the source repository. Consistently styled code also makes differencing CVS and local code easier (much easier).

Is the code self explanitory (naming and structuring are key here)?
Code styling is part of a coding standard, but there are less automatable constructs that should also be part of a coding standard. Naming is a very important one... Code reviews should ensure that proper care is taken that classes, objects, methods, parameters etc... are named clearly (no exceptions). Reading code should be like reading the instructions in a cookbook.
1 e
1/2 on
1 clv glk
1 tsp btr
chp the glk and on, then bt together with the e
fry the btr in a pan, then add mxt,.Fry for 10s on both sds.

is a lot less clear than

1 egg
1/2 onion
1 clove of garlic
1 teaspoon of butter

Chop the garlic and onion, the beat them together with the egg
Fry the butter in a pan, then add the mixture. Fry for 10 seconds on both sides

The same goes for code... Care should be taken to keep the abbreviations to the minimum (except when these are business acronyms). And most of all, this should be enforced by the conding standard and policed through a review.

Strucururing of the code is almost as important. The key to this is that generally code becomes alot less readable when the logical collection of "actions" becomes greater. I.e. the more lines of code to read, the harder to focus on what the code actually does. As a rule of thumb, I use the "15 lines per method" rule. If a piece of code is more than 15 lines long, there is a 95% chance that the method that contains the code is doing more than it hints (through its name) it is doing, which means that there probably is a good chance that the code should split into more cohesive units (methods, sometimes classes etc... depending on the granularity). When this practise is kept (and only in combination with proper naming), the code becomes alot more clear. Of course it is hard to set a clear rule about this in a coding standard... and this becomes a suggestion to be enforced where appropriate... The code review is there to ensure that the code is broken up into "cohesive units" where appropriate

Patterns and Anti-Patterns
When reviewing code, care should also be taken that the code does not attempt to solve problems that were solved elsewhere. What this means is that if a common problem is solved with different code, where a "simpler/clearer" existing solution could be applicable. Existing could mean elsewhere in the system, or maybe a "well known solution" published in literature (e.g. Design Patterns, by Gamma et al, or Patterns of Enterprise Architecture, by Fowler). Of course this adds the responsibility of maintaining a "catalog" of well known, properly documented solutions for problems (patterns), from which developers could obtain these patterns. The reviewer of code should also make sure that if problems are solved in code that are solved elsewhere (and known to work there), the code is augmented/refactored to apply the pattern. Please note that this is not the same as reviewing the design as a whole... it is only a review of a self-contained piece of code that solves a problem that is solved (and documented) elsewhere. I.e. the reviewer is expected to point out where patterens could be applied. Recurring patterns make it easy for code maintainers to read the code.
It is just as important for a reviewer to spot code that solves a problem in a manner "known to have caused other issues in the past", and recommend that these anti-patterns be refactored to a safer solution (usually a pattern). There is alot of literature documenting anti-patterns (including Manning Publication's Bitter..., series). However, there are undoubtedly cases where anti-patterns are in-house application or framework specific. These anti-patterns should also be documented in a "catalog".
As a side note... code reviews could be a very good start to documenting in-house patterns and anti-patterns, because in the beginning, these will be identified by team members that have more knowledge of the code base (i.e. problems that were solved in the past, both patterns and anti-patterns). For the "younger" developers, they provide an opportunity to "highlight" areas in existing code that were refactored (or could be refactored) to "well known" patterns that are applied in the industry.

Providing useful API documentation and code comments
Another area of code review should be the providion of API documentation. API documentation is important in 3 ways:
- To provide the developer a "high level" overview of which fine grained components (classes and interfaces) are there and how they should be applied
- To provide the developer with corner conditions in which these fine grained components are guaranteed to work/not to work, where naming alone is not sufficient.
- To provide the developer with a brief overview of what each fine grained component's function is from a business point of view.
The reviewer of the code should make sure that where appropriate this documentation is provided.
The reviewer should also police that documentation and code comments are not used "in vain". In-vain documentation/comments are used for instance rewording variable names or function names.
EG

/**
* this method displays the premium
*/
public void displayPremium()

The comment used here is clearly useless, since the name of the method already explains what the code does

/**
* Only displays the premium if the associated
* risk is not declined, otherwise 0 is displayed
*/
public void displayPremium()

In the case above, comments are used to augment non-obvious functionality, namely that the premium is only displayed if the risk is not declined... this cannot be ascertained from the method name.

The reviewer should also make sure that proper methods are used instead of comments over statements
E.G.

...
// if disabled just show the value, no dropdown <-- comment over statement
if (getDisabled() &&amp; parent != null) {
String displayValue = (String) RequestUtils.lookup(
pageContext, name, property, null);

if(!GenericValidator.isBlankOrNull(this.codeTranslator)) {
CodeTranslator translator = (CodeTranslator) RequestUtils.lookup(
pageContext, this.codeTranslator, null);
displayValue = translator.translate(displayValue);
}

if(displayValue == null) {
displayValue = "";
}

ResponseUtils.write(pageContext, ResponseUtils.filter(displayValue));
return SKIP_BODY;
}
...

could be refactored into a new method

private void showValueOnly() {
String displayValue = (String) RequestUtils.lookup(
pageContext, name, property, null);

if(!GenericValidator.isBlankOrNull(this.codeTranslator)) {
CodeTranslator translator = (CodeTranslator) RequestUtils.lookup(pageContext,
this.codeTranslator, null);
displayValue = translator.translate(displayValue);
}

if(displayValue == null) {
displayValue = "";
}

ResponseUtils.write(pageContext, ResponseUtils.filter(displayValue));
}

this method could then be called without the need for the comment like so:

if (getDisabled() &&amp; parent != null) {
showValueOnly();
return SKIP_BODY;
}

Note that the simplicity of this construct already tells the story, there is no comment needed

Are the corner cases in the code well guarded (Exception handling)
What the revierw should also look for, are corner cases. Corner cases are cases in the code where method calls or variable assignments are not guaranteed to change the affected component(s) into a stable (well known) state. There are 2 ways to guard for this in the code:

Assertions (i.e. exceptions)
Pre- and postconditions

With assertions, the code itsself checks that the parameters passed are guaranteed to bring the code into a valid state and once the affected component's state is changed assure that the state is valid. When the state is not the expected state an exception is thrown (application if at the application level or system when at the system level).
Pre- and postconditions do exactly the same, but at documentation (rather than implementation level). This can usually be done in the API documentation
When reviewing the code, the reviewer must see to it (to a reasonable degree) that the corner cases are covered in either of these was. The reviewer must also see to it that either method is used where most appropriate (within reasonable bounds). I agree that this is a grey area, but at least this should be discussed in the code review. The reviewer should also make sure that when assertions are used, the appropriate level exceptions are thrown. And in cases where code is called that throws exceptions they are properly handled (which includes forwarding). The reviewer must also insure that pre- and postconditions are observed (either handled or documented when ignored) by code that uses pre-/postconditioned functionality.

Do the unit tests test the main functionality provided by the developed unit?
Automated unit tests should test the functionality of a fine grained component. The reviewer should at least make sure that there are unit tests written for the changed or introduced components. At a more detailed level, the reviewer could also review the "isolation" of tests to make sure that tests do not rely on infrastructure, but are contained to test the unit (this speeds up the unit testing and also makes tests more reliable, since they do not rely on other code, that may or may not be working within specifications).
The reviewer will also need to verify (using the unit test logs), that the tests all pass AND have the appropriate coverage of the component tested.

Well, that was it for today.
Oh yes, and... we've finally managed to complete the "homegrown framework" change today... As was to be expected, we ran into pop-up after pop-up... but it's working... Would that we could have done it with Spring. Thank goodness the next few deliverables don't require "framework changes"

TTFN
(that is: Ta... Ta... For Now...)

Thought for Today

2008-05-24T19:15:00.001-07:00

Today, after about a whole day of restructuring our automated build, I am getting back to doing architecture.
I find it a bit hard to get back into it... it takes a while to re-focus from the practical, back to the theoretical, but at the same time it is good to just be able to not write documents the whole day long.

Automated Build & Deployment
I must say that I am quite pleased with the restructure of the automated build.
The tool:

Builds
Runs Unit Tests and Checkstyles and generates JUnit and Checkstyle Reports
Instruments Classes and generates a Coverage Report

It is the first time in my organisation that we've got this level of build automation, which is quite exciting for me.

We have also introduced and automated deployment process, by which we can identify which version of which application will be deployed to the Development Integration Environment and then move through the higher environments (test through to production) in a controlled manner.

Architecture
Well then, now back to Architecture.

For this specific part of the project, most of the architecture is "Hardware and Network Architecture", my least favorite view in the architecture. However, it must be done... I am also looking at the "Security View", since more than half of securing the System involve securing the Networked System.

Most of my focus is currently set to the definition of a "High Avialability" environment for our systems to run in.
I have been working on this part of the architecture (off and on) for about 2 weeks and I am almost ready for a first draft release to our "Infrastructure Services Group" and our "Security Services Group". With their feedback I will finally be able to finalize these two views and move on to the more exciting part "Application Architecture"