September 5, 2010
Received an email from a reader on the continuous alignment post and wanted additional examples. Practicing continuous alignment entails refactoring existing code to align assets better towards a reuse strategy.
Here are a few scenarios where refactoring opportunities can be utilized:
Horizontal logic mixed with app-specific logic: This is typically manifested in two flavors – cross-cutting functionality that is horizontal across several applications or domain-specific functionality that is applicable to a product line. Cross cutting functionality such as authentication, logging, error handling etc. can be refactored from app-specific to distinct components.
Redundant definition of business objects: maybe two or more of your projects are redefining a core concept from your problem domain and refactoring can help align them to a common definition. Once a common definition is used, add tasks into your iteration plans.
Manage application configuration: If several applications use ad-hoc set of practices to manage runtime configurations (e.g. xml configurations, property files etc.), refactoring them to use a consistent strategy would certainly make sense. This refactoring can be done one component at a time if time constraints make it harder to transform an entire suite of components in the app.
Leave a Comment » | 
Reuse, agile, refactoring | Tagged: software reuse, refactoring | 
Permalink
Posted by vijaynarayanan
August 22, 2010
I wrote earlier about using open source software for fulfilling functionality prior to building a custom implementation. Many projects have the need to transform object to text or XML – e.g. return XML response for REST-based services or return JSON string to support a web application etc.
Freemarker is a templating engine that can be leveraged to perform object to text transformations – with freemarker it is easy to generate RSS feeds or delimited text or plain old XML very easily. Below are some code fragments that illustrate freemarker usage:
Below is a code fragment for setting up the template configuration:
try {
// Initialize configuration;
cfg = new Configuration();
cfg.setDirectoryForTemplateLoading(new File(templatesLocation));
cfg.setTemplateUpdateDelay(0);
cfg.setTemplateExceptionHandler(TemplateExceptionHandler.HTML_DEBUG_HANDLER);
//Use beans wrapper (recommmended for most applications)
cfg.setObjectWrapper(ObjectWrapper.BEANS_WRAPPER);
cfg.setDefaultEncoding("ISO-8859-1");
//charset of the output
cfg.setOutputEncoding("UTF-8");
//default locale
cfg.setLocale(Locale.US);
} catch (Exception e) {
//handle the exception
}
The templatesLocation variable is the path to a folder with freemarker templates (referred to as FTL templates). These are similar to templates used with frameworks such as Velocity. For example, below is a template fragment:
<Name>${myBean.firstName} ${myBean.lastName}</Name>
“myBean” is the java object that has first name and last name properties supported by JavaBeans style getXYZ() methods.
Below is the code fragment when trying to invoke a template with a java object:
// loading the template file
Template template = //get template from a map
Writer out = new StringWriter();
template.process(dataObject, out);
String strResponse = out.toString();
The above code fragment essentially takes a java object (dataObject) as input and creates a string as output. Using the template above, the output for example could be:
<Name>John Smith</Name>
Freemarker also supports loops and conditions and offers a rich library of built-in functions as well.
Leave a Comment » | Reuse, open source | Tagged: freemarker, object transformation, refactoring, software reuse, template engine | Permalink
Posted by vijaynarayanan
August 15, 2010
I have heard some variation of the following line from developers, technical leads, and architects – “we want to make things more reusable, but we don’t have the time.”
There is always a deadline (or many deadlines) to meet and technical debt to accumulate. Since we are always in a hurry, it helps to be aware of what should be reusable – even if we won’t get to it in this iteration . So here are some ideas that can help you decide whether or not a capability should be developed for reuse:
- is the capability unique to your enterprise? i.e. it captures logic and/or process variations that provide competitive differentiation.
- is the capability making something incredibly hard/defect prone simpler and/or easier?
- is there a desire for customers to have a capability across business channels? i.e. from the web, from a mobile device etc.
- is it specific to your domain and potentially relevant to multiple applications in the domain? this may or may not be obvious – if it isn’t, delay commitment.
- is the capability only available in a particular technical platform but is solving an often needed problem?
- is it automating boiler plate code generation or preventing defects?
- is there an in-house/external alternative that achieves your functional requirements? if so, seriously consider stopping investment in the asset.
This is a starter list – the idea that we keep coming back to is this – treat a reusable asset like a real investment. Every iteration and release is an opportunity to review and update the investment. When you make a decision, continuously refactor to make the capabilities less app specific and reusable.
Leave a Comment » | Reuse | Tagged: agile, Asset, code generation, refactoring, software investment, software reuse, strategy | Permalink
Posted by vijaynarayanan
July 14, 2010
Code reviews can be extremely effective driving systematic reuse. To be sure, there are multiple objectives with code reviews (e.g. adhering to naming standards, detect defect, write consistent comments, etc.). Additionally, they can help with reuse in the following ways:
- Reviews happen prior to code being placed in production – they give you a chance to extract, build, or integrate reusable assets.
- Code reviews often identify opportunities to refactor – refactoring to reuse. Have you ever had a review where someone said, “you know what, you should talk to Joe, since he is building a similar thing…” or “…we should use the existing service for implementing this story.”
- Reviews help discover reusable assets – you might include classes and interfaces (not necessarily neatly demarcated) – in a component that can really be split up into two or more components. It may be appropriate to slice up the logic to ensure the existing component isn’t too monolithic
- Reviews are very effective in preventing defects – with reusable assets, quality is everything and the act of reviewing them is critical to their stability and production-readiness. These can be extended to unit tests and documentation as well.
- Reviews are a neat opportunity to communicate to at least a sub-set of the team what reusable assets exist and how they can be leveraged. Often times, when assets are mentioned as-is, they may not be that well received. Place them within the context of a real project, a real deliverable, and a tangible need – now the communication is much more effective.
As more developers pitch in and learn from each other, the reviews will become a critical part of how you develop and evolve reusable assets.
1 Comment | Reuse | Tagged: software reuse, agile, code reviews, refactoring, success factor, systematic reuse | Permalink
Posted by vijaynarayanan
July 11, 2010
You want to build reusable assets in an agile manner – avoiding a significant design effort upfront and evolving behavior over time. Why? Because building for reuse involves several steps: the right abstractions have to be identified, appropriate variations have to be modeled and accounted for, and the asset has to be generic enough for use beyond a single project.
This is hard to get right the first time – often, business requirements aren’t clear from the early on making it tricky to identify reusable assets. More importantly, reuse adds project risk – specifically risk to the timeline. Always ask yourself if it is worth making the extra investment – if you aren’t sure delay commitment.
Capture possible enhancements to your codebase via an issue tracking tool and you can always assign those enhancements to future iterations. When you implement a story and you see the opportunity for making something reusable, consciously align classes and interfaces for reuse. Refactor, refactor, and keep refactoring – because only with multiple iterations is your asset going to be increase it’s reuse potential. Remember – very often, the asset would not be used as-is. It will need changes – patches, enhancements, major redesign even – before it can be leveraged across projects.
Leave a Comment » | Reuse, refactoring | Tagged: agile, interfaces, refactoring, software reuse | Permalink
Posted by vijaynarayanan
April 25, 2010
One of the often-repeated reasons for not starting a reuse program is the upfront investment required for building the initial set of reusable assets. This is a legitimate impediment that can be addressed by taking advantage of existing code in your team. When you evaluate existing assets for their reuse potential, there are a lot of factors to consider. Here are a few salient ones:
- Fit within product line: is the asset of relevance to one or more applications in your domain? You want to invest in assets that encapsulate business functionality that can be utilized in multiple business processes and applications. Similarly, if there are assets with business relevance but in a area that your organization intends to divest out of – you will be less inclined to use them.
- Coupling: How tightly or loosely coupled are the pieces within an asset? sometimes the asset itself might be mixed in – tightly coupled – with a lot of extraneous code. Business logic might be mixed with data access, presentation, and even specific calls to external systems. Every one of these aspects introduces coupling that will need to be assessed thoroughly.
- Integration: what is the effort required to integrate the reusable asset with applications? The asset might be very difficult to integrate because of platform specific requirements or because of language needs.
- Business Assumptions: are there assumptions that the asset makes about business rules or business activities? if so, are these assumptions still relevant? will the rules need externalization/refactoring? Often, business assumptions are lost due to lack of alignment between business concepts and abstractions in code.
In a followup post, I will elaborate on robustness, scalability, deployment, documentation & samples. Without thinking through these aspects it is risky to introduce new assets for reuse. You will quickly discover that your consumers are unforgiving when it comes to asset quality. Additionally, a huge learning curve will drive away potential and existing developers and technical leads from evaluating assets for use with new applications.
Leave a Comment » | Planning, Reuse | Tagged: business rules, integration, legacy assets, loose coupling, refactoring, software reuse | Permalink
Posted by vijaynarayanan
April 22, 2010
There are so many reasons why continuously refactoring code is a good idea – in fact, it is a sound investment for the overall health of your codebase. So, what could be some reasons why we fear doing refactorings? what could be the impediments to making changes?
In my experience, the #1 reason why developers fear refactoring is the lack of automated regression tests. This is why Martin Fowler emphasizes the need for tests prior to pursuing refactorings in his seminal book Refactoring. Without a comprehensive suite of tests, developers cannot be confident that changes to the code didn’t break existing functionality and it didn’t introduce new defects.
There are other reasons as well for fearing refactoring:
- Not enough time during development – this is such an often repeated reason for a variety of issues
Here is the rub though: we learn most about the domain and the limitations of existing code with experience. This tends to happen at the “end” of an iteration or release cycle. Naturally, we don’t want to jeopardize our release to do refactorings. This is precisely why agile advocates the notion of continuous refactoring iteration after iteration. Your code reflects the state of the software (and the associated knowledge of the domain) at a snapshot in time. It is a work-in-progress – remaining that way till the product ceases to exist or be maintained.
- Lack of disciplined effort to translate new domain knowledge into existing code. As a project proceeds, developers learn more about the domain and the gaps in their knowledge with respect to the domain. These gaps typically manifest themselves in various forms: needless abstractions, insufficient flexibility with known variations in the domain, and lack of domain-relevant concepts being modeled as first-class citizens.
- Insufficient knowledge on using refactoring tools (e.g. using an IDE such as Eclipse, there are a plethora of refactorings can be implemented rapidly).
- Lack of knowledge about refactoring tactics – moving methods, creating interfaces, replacing if..then logic etc. – that are necessary to keep a tidy, effective codebase
- Unwillingness to improve the codebase on a continuous basis
Leave a Comment » | agile | Tagged: agile, continuous refactoring, iteration, refactoring, software reuse | Permalink
Posted by vijaynarayanan
April 18, 2010
There is always an element of additional complexity when building resuable assets – whether it is because of externalizing configuration, adding additional interfaces/classes to provide flexibility, or introduction of additional layers of abstraction (to name a few). There is also the increased cost of design, testing, and integration with reusable assets. The question isn’t whether reusable assets are more or less complex – a more pragmatic question would be:
is the additional complexity absolutely essential and worth the cost?
This is a straightforward question to answer if you have visibility into what is coming up in the near future. If this isn’t the case – which is “most of the time” – the question becomes a trickier one. One way to address this issue is to introduce domain-relevant abstractions.
Instead of guessing what should and shouldn’t be an abstraction – work with domain experts and uncover true domain-relevant concepts. For example: Let’s say you decide to build a reusable library for providing customer data. Say this is used to populate a financial statement that shows a customer’s net worth (i.e. financial assets). Initially your software might have used the checking account balance to report this value. Why? Because, that was the only kind of account that was used to calculate this value. In the initial version the team might have thought ‘net worth’ was a data attribute – a number that is derived from the checking account balance. Over time, as domain understanding deepens, ‘net worth’ might become – not just a single account’s balance but a whole host of other things (e.g. accounts where the customer is a joint account holder including not only checking accounts but also savings, brokerage, etc.). ‘Net worth’ might still be a single number but it would have evolved to encompass a different meaning than just a single account’s balance. Not to mention business rules that have to be applied based on a plethora of account and client characteristics and quickly this would evolve into something more complex.
At the time of the initial release your team might not have this knowledge – and that is perfectly okay! Key is to evolve the codebase along with your increased understanding of the domain. Will net worth be it’s own class or interface in the initial version? If you don’t have even the preliminary understanding, why introduce needless complexity? wouldn’t it be better to refactor to reuse rather than build for reuse with an imperfect understanding?
1 Comment | Design, Reuse, agile | Tagged: abstraction, agile, domain driven, interfaces, refactoring, Reuse, software reuse | Permalink
Posted by vijaynarayanan
April 17, 2010
#5 – Replace Custom Implementations With Open Source Equivalents
I realize this is a very large category with possibly several dozen examples. In this post, I will highlight this strategy using the Apache Commons IO API. Many applications require the need for accessing file data – reading input business data or even temporary file data is a common need. Typically, you have some class that opens a file, reads data line by line, and either returns a custom java object or a string buffer.
FileReader fr = null;
BufferedReader reader = null;
try {
fr = new FileReader(strFileName);
reader = new BufferedReader(fr);
String line = reader.readLine();
while (line != null) {
//do something with the line of data...
line = reader.readLine();
}
} catch (IOException e) {
e.printStackTrace();
} finally {
try {
if (reader != null) {
reader.close();
}
} catch (IOException e) {
e.printStackTrace();
}
}
How many times have you written this kind of logic? When you look to simplify this or want to reduce repetition, consider the Apache Commons IO library. The FileUtils class offers just the method you need for accomplishing the often needed line by line data access to a file. It is trivial to use. For example, see below:
import org.apache.commons.io.FileUtils;
//other lines of code and class declaration omitted...
String strFileName = //path to file...
try {
File f = new File(strFileName);
List fileDataLines = FileUtils.readLines(f, "UTF-8");
} catch (IOException ioe) {
ioe.printStackTrace();
}
That’s it – giving you the same functionality using a far simpler interface. There are several advantages to using these libraries – they are open-source, well documented and tested, and eliminate a lot of redundant code in your application. Travel light and only code stuff that you absolutely must. As I have highlighted before – reuse and agile go hand-in-hand. Less custom code you write, less maintenance for your team.
1 Comment | Reuse, agile, refactoring | Tagged: apache commons io, fileutils, open source, refactoring, software reuse, systematic reuse | Permalink
Posted by vijaynarayanan
April 17, 2010
Download Checklist
Here is a checklist for ensuring that your service capabilities are unit tested effectively. These questions can come in handy when validating test coverage or when doing code reviews with fellow team members. I have used this checklist extensively in all my SOA development efforts and has helped with improving the quality of the services. The check list covers:
- functional testing
- error handling
- data validation/formatting
- performance testing
- data binding/transport interfaces
Feel free to add/customize this checklist based on your team’s unique needs. I hope you find this resource useful!
Leave a Comment » | Reuse | Tagged: agile, checklist, refactoring, Reuse, service capability, services, SOA, testing | Permalink
Posted by vijaynarayanan
