January 1, 2012
Tip #29 – Automate Documentation on Reusable Assets
Happy new year 2012 
What is one key reason developers have a difficult time finding and evaluating existing assets? Lack of robust documentation including what the reusable asset isn’t meant to do. Though it is a critical success factor, maintaining documentation manually is a time consuming task and is the first item that gets left out when the development team is racing to meet a deadline. It will be useful to generate documentation on service clients or library client code snippets alongside the provider code. Automate documentation as much as possible – this will come in handy when fixing bugs, integrating new consumers, as well as integrating documentation within IDEs. Here are a few examples of doing this:
- Maven javadoc plugin for example can generate javadoc style HTML documentation for various java and web modules
- Maven site deploy can be used to publish generated artifacts to a remote host
- XSL stylesheets can be used to generate HTML documentation from XML schemas (XSDs) – this can be handy when exposing reusable services (e.g. using XS3P)
Leave a Comment » | 
Reuse | Tagged: documentation, software reuse, tips | 
Permalink
Posted by vijaynarayanan
May 2, 2011
Distribute Configuration For Various Testing Needs
If a reusable component requires runtime configuration (properties, XML files etc.) alongside the binaries, make it easier for the asset’s consumer to integrate these artifacts in their tests. For instance, using maven assembly the configuration files can be packaged as a jar file and added in the test scope. This will make the configuration available in the classpath when executing unit tests in the module. The configuration can be packaged per environment and using the dependency classifier the appropriate artifact can be used. This approach works for integration and performance testing as well – for instance, performance tests might use a different set of values for the configuration artifacts since they execute in a dedicated environment.
Leave a Comment » | Reuse | Tagged: artifact, configuration, maven, properties, software reuse, testing, tips | Permalink
Posted by vijaynarayanan
November 6, 2010
Use Maven Assemblies for Packaging Configuration Artifacts
The maven assembly plugin can be used to generate separate artifacts for environment-specific configuration files. This is very useful to separate binaries (jar, war, etc.) from configuration (xml, properties files, etc.). This enables deployment of a binary across any environment. Reusable components are often used in several applications and processes and they often have configuration information. Your clients will want to customize the configuration for testing/altering behavior and it is critical that your build process separates binaries from configuration.
Here’s the snippet for adding the plugin in the POM file:
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>2.2-beta-2</version>
<configuration>
<descriptors>
<descriptor>test-assembly.xml</descriptor>
</descriptors>
</configuration>
<executions>
<execution>
<id>zip</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
Here’s an example packaging a zip:
<assembly>
<pre> <id>some-assembly-identifier</id>
<formats>
<format>zip</format>
</formats>
<includeBaseDirectory>true</includeBaseDirectory>
<fileSets>
<fileSet>
<outputDirectory><!--add folder--></outputDirectory>
<directory>${basedir}/target/classes</directory>
<includes>
<include>*.xml</include>
</includes>
</fileSet>
</fileSets>
</assembly>
Leave a Comment » | agile, Reuse | Tagged: assembly, configuration, maven, software reuse, tips | Permalink
Posted by vijaynarayanan
July 10, 2010
Tip #26 – Build Reusable Services
The following are useful tips when designing and implementing reusable services.
Expose only logical data attributes and “standardized” values to external consumers in the service contract. This will ensure that the data service has maximum flexibility to change physical system implementations underneath and the consumer will not be adversely impacted.
Reuse business object schemas across data service operations and while preparing WSDL documents. This will ensure logical data model alignment as well as consistent definition of business objects simplifying consumption and maintenance effort.
Expose event driven publication services for data propagation to downstream consumers using standard publication messages. This will greatly reduce (and potentially eliminate) the need for source specific messages and needless data transformations. Standard publication messages could be versioned and new consumers could be added via configuration on a messaging broker without requiring development effort.
Provide multiple flavors of services based on commonly used use cases for the data service. A light flavor of a service will be useful for clients who do not want to parse a large business object message returned by the full flavor.
Strive for abstraction of data source specific semantics in order to insulate the consumer from physical data source processing/logic. This practice applies to identifiers, data values, data structures, and data orchestration logic that could be coupled to a physical source if proper care isn’t taken.
Prefer reliable transports when invoking data services asynchronously. Although it is possible to simulate asynchronous processing using transport protocols such as HTTP it is not advisable to do so. In the event the data consumer becomes unavailable messages are lost.
Leave a Comment » | Design, Reuse, SOA | Tagged: abstraction, services, software reuse, tips, web services | Permalink
Posted by vijaynarayanan
April 14, 2010
Tip #25 – Leverage Code Coverage Tools
Code coverage tools help with defect detection and prevention as part of continuous integration. I emphasized the importance of automated tests with regard to resuable assets – code coverage is no less important.
Code coverage reporting provides a window into the health of your codebase.
- the depth of your automated tests – what percentage of code is being executed by the tests?
- are there unused blocks of code – including functions, even classes – that are not executed?
- they are invaluable in helping detect complex code – are some classes too bulky/ripe for refactoring? Code coverage will make these painfully obvious to the developer.
Code coverage thus not only helps you identify opportunities for better tests it also helps you eliminate dead/bloated code and rip apart code that is too complex. I wrote earlier post on developing reusable assets for use first – I recommend identifying extensions/flexibility on a as-needed basis for reusable asset evolution. Code coverage will point out areas for achieving this objective as well.
Getting started is very simply – ff you are using apache maven2 for instance in the java world, it is extremely simple to set these up and use them by adding a few entires to the pom.xml file. Below is the plugin declaration for Cobertura – for plugin’s full usage instructions go here.
<plugins>
…
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>cobertura-maven-plugin</artifactId>
<version>2.3</version>
</plugin>
</plugins>
You can run code coverage by simply executing: mvn cobertura:cobertura from the project root folder- this will generate instrumented java classes, execute automated unit tests, and produce a code and branch coverage report.
1 Comment | Reuse | Tagged: agile, automated tests, cobertura, code coverage, continuous integration, refactoring, software reuse, systematic software reuse, tips | Permalink
Posted by vijaynarayanan
November 25, 2009
Tip #24 – Identify common behavior and encapsulate it
Looking for common behavior across classes is an effective way to reuse behavior. When you find yourself cutting and pasting code, take a step back and reflect on the common behavior that is being implemented. If the duplication is due to the same behavior realized in different ways, introduce a new interface. If multiple objects have the same functionality and can derive from a parent object, introduce an inheritance hierarchy.
This can be done in an iterative fashion as well – if you failed to recognize an interface initially that is okay. Look for opportunities to refactor existing code to introduce a new interface. For example, you can use the Eclipse IDE’s refactoring feature – extract interface – to create a new interface from an existing class.
Why is this important for systematic reuse? Because, by isolating and realizing common behavior you reduce the need for multiple components and classes to re-implement the same functionality. If two classes need the same piece of data, or if they both connect with the same external system, why would you want to code them separately?
Like this post? Subscribe to RSS feed or get blog updates via email.
Leave a Comment » | agile, Reuse | Tagged: common behavior, inheritance, interface, tips | Permalink
Posted by vijaynarayanan
November 11, 2009
Tip #23 – Design for migration within the product line
Graceful migration within a product line is an often overlooked design trait but is critical for effective systematic reuse. Your products get upgraded or downgraded within a product line. Think of when you switched phone plans from a single user to a family plan or when you signed up for viewing premium content on an online website. Your design needs to support this in a seamless fashion. The design could support some form of licensing, a policy manager that knows your valid subscriptions and entitlements, and a means to migrate or setup data for a different flavor of a product. You cannot lose customer data and preferences if they upgrade to a different plan or a product in a product line. Reusable assets have to store, access, and update relevant data as a new version is introduced or bug fixes are made.
Like this post? Subscribe to RSS feed or get blog updates via email.
Leave a Comment » | Reuse | Tagged: product lines, software reuse, tips | Permalink
Posted by vijaynarayanan
November 6, 2009
Tip #22 – Ensure Service Capabilities Stay Effectively Decoupled
The rationale for contract-first services (as opposed to code-first) is to effectively decouple service capabilities from needless implementation-specific, vendor-specific, and data-source specific realizations. You put the initial service capability out and ensured that the contract is decoupled – no legacy system specific details, no database-vendor or technology platform-specific attributes are present and your consumers are happy. So, are you done? Well, no…because we all know that the technology environment, business requirements, regulations, and continuous innovations are the realities of modern development. You have to be careful not to succumb to these pressures and tread towards needless coupling. It is very easy to add one more attribute or element to your service contract and not pay attention to tight coupling being introduced.
As you add new versions, introduce enhancements, and make bug fixes take care not to introduce needless coupling. You can tie in code reviews – focused specifically around service contracts – to ensure this happens as part of your overall governance strategy. I will post detailed examples for this quick tip in a follow up post.
Like this post? Subscribe to RSS feed or get blog updates via email.
Leave a Comment » | agile, Reuse, SOA | Tagged: decoupling, governance, services, software reuse, tips | Permalink
Posted by vijaynarayanan
October 28, 2009
Tip # 21 – Identify Repetitive Steps Consumers Perform
There are a variety of places to look for reuse opportunities – one that is my favorite is looking for patterns with customer integrations. If a customer is setting ten properties to execute a common service call or method, why not provide a convenience function to accomplish the same in fewer steps? The other classic example is initializing objects. If every consumer is creating the same set of objects and initializing it in a specific way – resulting in a lot of repetitive code – you can provide a factory class or a façade interface. Additionally, look for activities that customers do that should be part of the reusable asset or can be useful to others. For instance, maybe after receiving output your customer converts that data to another format (say from XML to JSON or XML to plain text) – why not provide an option to get that right out of the reusable asset? Note of caution here though: what I am referring to is only common capabilities that aren’t specific to a single consumer. If you place logic that is specific to a consumer the asset is no longer reusable.
Like this post? Subscribe to RSS feed or get blog updates via email.
5 Comments | agile, Design, Reuse | Tagged: abstraction, consumer, initializing, repetitive, software reuse, tips | Permalink
Posted by vijaynarayanan
October 18, 2009
Tip #20 – Minimize channel specific dependencies and behavior
If you want to build assets that are reusable across distribution channels you should encapsulate channel specific data attributes and behavior from the rest of the logic. Often times I have built assets without taking this into consideration and have gone back and refactored the channel logic out of the domain components. If you know that an asset is going to be offered via multiple channels you can certainly take it into account earlier. How will know this? The first place to look will be your systematic reuse roadmap. Is your business planning to offer a capability in a new distribution channel such as interactive voice response or for mobile/iPhone users? Even if it’s too late for the current iteration you always add it to the list of planned refactorings.
Below are examples of channel specific couplings and suggested design alternatives:
| Channel |
Coupling Example |
Suggested design alternative |
| Online Portal (Self-Service) |
Your asset assumes that the caller will provide a certain input identifier always. E.g. login user name |
Define an enumeration to support login user name and other kinds of identifiers as input. E.g. your interactive voice response might use social security number as input while your call center might use a customer identifier instead. |
|
Your asset assumes that the caller will only want a subset of data.
E.g. asset only provides name and address data for a customer |
Offer multiple flavors of data objects. Based on channel’s preferences a particular flavor can be returned. E.g. Online portal could use a full customer profile while a call center could use a partial customer profile with certain data attributes masked for privacy. |
| Branch |
Your asset assumes that the caller will be invoking from a particular technology platform that is specific to the branch. E.g. the asset takes a workstation identifier as input. |
If you must capture workstation identifier put it as an optional parameter or a generic name/value pair type data structure. |
This list is just an example and obviously your environment might contain additional channels and different types of channel couplings. As with everything else, you don’t need to rush into fixing them. If a user story requires an asset that has a certain coupling, you can refactor just in time.
Like this post? Subscribe to RSS feed or get blog updates via email.
Leave a Comment » | agile, Design, Reuse | Tagged: branch, channel specific, online, software reuse, tips, variations | Permalink
Posted by vijaynarayanan
