Toward smarter dependency constraints (patterns to the rescue)

Low coupling between objects is a key principle to help you win the battle against software entropy. Making sure your dependencies are under control matters. Several tools can enforce dependencies restrictions, such as JDepend. However in a real project with many classes, packages and modules, the real issue is how to decide and configure the allowed and forbidden dependencies. Per class? Per package? Per Module? Based on gut feeling? Is there a theory for that?

Of course, in a layered architecture, the layers specify the dependencies. This is not bad, but I am sure we can do better.

Smarter dependencies

To go further, I suggest expanding our vocabulary of concepts. In OO languages such as Java, everything is a class (or an interface), grouped into packages. Such classification is not really helpful. Fortunately, several books provide ready to use vocabularies in the form of patterns languages (not only design patterns, but patterns in general). Some of these patterns are foundations on which rules to manage dependencies can be proposed.

Disclaimer: the dependencies rules suggested below are hypothesises to be debated and verified against a corpus of actual projects, I would be happy to be given counter-examples and counter arguments.

The child really depend upon the mother
The child really depend upon the mother

Domain Driven Design

The book Domain Driven Design by Eric Evans defines a rich vocabulary of concepts used in every application, and we can leverage that vocabulary to propose some dependencies principles between them:

  • ValueObject never depends upon Entity nor Services
  • Entities should not depend upon Services (maybe not a hard rule)
  • Generic SubDomain should not depend upon Core Domain
  • Core Domain should not depend upon Cohesive Mechanism (the “What” should not depend upon the “How”)
  • Domain Layer should not depend on any infrastructure code
  • Abstract Core module never depends on its specialized or implementation modules

Analysis Patterns

The book Analysis Patterns by Martin Fowler also provides patterns as a richer vocabulary, from which we could propose:

  • Elements from a Knowledge Level should not depend upon elements from the corresponding Operation Level

I did not find that rule written in the book but every example appears to support it. Considering that classes and subclasses in usual OOP are a special case of Knowledge Level built-into the language, this would lead to:

  • Abstraction never depends upon their Implementations

which is similar to the second part of the Dependency inversion principle by Robert C. Martin:

Abstractions should not depend upon details. Details should depend upon abstractions.

Since many analysis patterns in the Analysis Patterns book involve the Knowledge Level pattern, this single dependency rule already applies to many analysis patterns: Party Type Generalizations, Measurement, Observation, Protocol, Associated Observation, Measurement Protocol etc. The pattern Quantity can be seen as a specialized ValueObject (see Domain Driven Design above) hence should also not depend on any Entity nor Service.

Design Patterns

The book Design Patterns: Elements of Reusable Object-Oriented Software by Erich Gamma et al. presents the classic design patterns. These patterns define participants which are named.  In the pattern participant ignorance principle I discussed the concepts of ignorant Vs. dedicated participants within a pattern, and their consequences for dependencies:

  • Ignorant pattern participants should never depend on dedicated participants
  • Pattern participant never depend on the “Client” participant
  • For each ConcreteX participant, the corresponding abstract X never depends on it (Abstraction never depends upon their Implementations)

In practice, this means:

  • In the Adapter pattern, the Adaptee should not depend upon the Adapter, and the Target should depend upon nothing
  • In the Facade pattern, the sub systems should not depend upon the Facade
  • In the Iterator pattern, the Aggregate should not depend upon the Iterator; however every Java collection is a counter example as they contain their own ConcreteIterator.
  • In creational patterns (Abstract Factory, Prototype, Builder etc.), the Product and ConcreteProduct should not depend on the dedicated participant that does the allocation (the Factory etc.)
  • And so on for other patterns, some of which being already discussed in the pattern participant ignorance principle.

In short, if we look at the design patterns as a set of types with inheritance/implementation, invocation/delegation and creation relationships between them, the dependencies should not flow in the reverse direction of the relationships; in other words, using UML arrows, the dependencies should only be allowed in the direction of the arrows.

Addiction to sugar is a kind of dependency
Addiction to sugar is a kind of dependency

Patterns of Enterprise Architecture

In the book Patterns of Enterprise Application Architecture by Martin Fowler, the Separated Interface Pattern proposes a way to manage dependencies by defining the interface between packages in a separate package from its implementation. This is similar to the Dependency inversion principle, as discussed here, which states:

A. High-level modules should not depend upon low-level modules. Both should depend upon abstractions.

By the way this is also very similar to the recommendation in Domain Driven Design:

Abstract Core module never depends on its specialized or implementation modules.

Finally, in the spirit of UML stereotypes that we sometimes put on packages to express their intent:

  • Utils never depends on anything but other Utils

What for?

If we manage to make every use of the above pattern explicit in the source code, for instance using Java annotations or simply Javadoc tags, then it becomes possible for a tool to deduce dependencies constraints and automatically enforce them.

Imagine, just add @pattern ValueObject in your Javadoc comment, and voila! A tool is now able to deduce that if you happen to import anything but basic java.* you must be warned.

Of course the fine tuning of the default behavior can take some time (do we accept that ValueObjects may depend upon low level utils like StringUtils? Probably yes), but the result will at least be stable regardless of the refactorings.

Given the existing variety of patterns over there, I am confident that just any class or interface within a project can be declared as being a participant in at least one pattern, and have therefore its dependency constraints deduced at the same time.

Read More

After Technical Debt, technical Options

In finance, options are powerful tools for traders, and many design practices including design patterns can be seen as options. Options can -perhaps- yield a great benefit for a certain and immediate cost. If this cost is cheap enough it can be quite attractive.

An option to buy a stock is a right to buy the stock at a predefined price (let’s say EUR25) before a given date in the future. Until this date, you can freely exercise the option (i.e. buy the stock at EUR25), or not (do nothing). Of course if it happens that the stock price is greater than EUR25 (let’s say the stock is now EUR35), if you exercise the option you earn money (EUR10), and for that reason the option is worth something (EUR10 here, or even more if we expect the price to go even higher in the future).

In finance, the price of the option is directly linked to the expected benefit it can bring, even though this benefit is not certain. To be more precise, the more the stock price moves up and down, the bigger the option value: this instability of the price is called volatility, and you can think of it like a standard deviation in statistics. Options traders actually trade volatility: the higher the volatility (i.e. the less stable the prices), the more valuable the option.

Many design practices can be seen as options, and some are indeed cheap, almost free options. A free option is something that a reasonable investor cannot refuse to get, since it costs nothing while it can perhaps yields a benefit: this is actually an uncertain version of a “free lunch”. A design practice that would cost nothing is hard to resist, since it yields potential return in exchange for nothing.

In the spirit of the Technical Debt, we will focus on the cost of maintaining the code over time. Any change to the code must be weighted in accordance to the burden it will bring compared to its benefit.

Plenty of options here
Plenty of options here

Technical options in the code

In practice, everything that improves the flexibility of the software is de facto like an option: it creates additional opportunities that we can use or not in the future. Typically, it can enable the designer to change his mind at a later stage at no cost, or to defer a design decision.

The design principle to code against abstractions rather than implementation comes immediately to mind: coding against interfaces is probably the number one technical option. Therefore the question is: given this piece of concrete code, should I introduce an interface and reference the code through the interface, or should I leave it like that? Just like in finance, the answer is: it depends on the upfront cost of the option (adding the extra interface) compared to the anticipated stability of the feature the code is doing (is it likely to change in the future?).

In this case, the upfront cost depends on the tools (with modern IDEs with wizards and refactoring capabilities it is easier to add or even extract an interface automatically), and perhaps on what you like to do or not (if you hate having too many classes then adding an interface will cost you more, subjectively). Some commercial source control systems that are not convenient with widespread refactoring also make the cost of future changes much higher, and as such they encourage building flexibility upfront.

Going further, many design patterns can be considered as options to improve flexibility for a minimal cost. Out of the GoF patterns, the patterns Abstract Factory, Strategy, State, Visitor, Iterator, Bridge and Builder directly plan for easy change of behaviour or extension in the future (typically through additional interfaces as well), and thus are simple yet efficient ways to buy technical options.

Various elements combine together for bigger value added
Various elements combine together for bigger value added

Technical options Vs. YAGNI

Knowing the future is hard, and YAGNI is there to remind us that. If there are practices that cost a little to introduce and that can bring benefits later, and if we are so poor at anticipating change, why not just introduce them later? This is right, in most cases YAGNI applies, unless we can anticipate a need. The funny thing is that while the introduction of interfaces (directly or through the patterns mentioned before) creates opportunities to vary the implementations, it also creates opportunities for other opportunities. The new interface enables the addition of non-intrusive structural patterns that revolve around an existing interface, such as Decorator, Composite, Proxy, Adapter, Null Object, and every combination of them as suggested by the Interpreter pattern. (This introduction of such patterns, by the way, is precisely what most IoC containers, application servers and AOP frameworks do to add functionalities). How these patterns combine together under the common “umbrella” interface is kind of fascinating to me, and it always reminds me about the Network Effect: the more we use an interface, with implementations or opportunistic patterns, the more useful it becomes. I believe that a net of patterns like that can become so useful that it becomes irresistible. You will gonna need it.

Of course there is nothing really new in all that, nothing more than a new metaphor to help explain to managers. Even if they do not know what an option is, I am sure they can understand the concept very quickly.

I have been pushing this approach that I called “Think options, not solutions” in my former team to emphasize that we can build the system even if some of its business behaviours are not completely known yet, as long as we can define their contours and start with an arbitrary solution. The goal is that we are confident we can change it later with no pain. This was justified from a business point of view because we did not know what the market was expecting, for the product (an interest rate swaps multilateral trading facility) was too novel. In that environment, change was definitely not something we feared, rather the opposite: it was stimulating.

Just like traders speculate on volatility using options, developers can speculate on the stability of the business features using (or not) design practices that increase flexibility. The little extra effort to introduce these practices must be weighted by the expectation that it will be useful. And just for the fun, anyone interested in computing the value of a technical option using the Black-Scholes pricing model?

Read More

Akai MPC program editor in Java

I juste wanted to automate the creation of programs for my Akai MPC500 sampler/groove machine, for my personal needs, and I ended up releasing a piece of software to sourceforge. It is called MPC Maid, read “assistant of the MPC”, here is a screenshot of the program editor:

MPC Maid program editor view
MPC Maid program editor view

The MPC file format was freely available on the website of Stephen Norum, very well documented. However my day job is to design and code big financial server-side systems, hence coding at the byte-level was refreshing…

Chop loop into slices

I had been playing around with audio/Music Information Retrieval (MIR) recently for fun, so I took the opportunity to integrate some of that, in the form of a really simple loop slicer.

Audio Slice Editor view
Audio Slice Editor view

You just drag and drop a WAV file from the file explorer into its waveform editor, then it analyzes the audio samples to detects the beats. There is a slider to adjust the sensitivity of the detection, which means this is not a totally automatic algorithm.

The idea for the detection comes from the article “Beat Detection Algorithms” from Frédéric Patin, with some personal modifications. In particular I have added a toggle to prevent a detection immediately after another, and a zero-cross detection to cut the slices on a zero-crossing, in order to reduce the glitches (but of course this is not enough to be perfect, fortunately the MPC has a convenient small decay at the very end of every sample, which solves the problem).

The idea is to compute the energy in sliding time-domain windows,then compare the energy of each window against the average in the surrounding; when it exceeds it enough, there is a beat.

Since many loops available are commercial quality, their length gives the tempo with an extreme accuracy. I used that to generate a MIDI file of the groove of the loop. Coupled with the program edition this allows for exporting the slices, the MPC program that uses them, and the MIDI sequence of their placements, in other words this is roughly equivalent to the REX file idea.

Native-looking but fully portable

Making sure that the software is fully portable and looks native in Mac OS X and in Windows requires careful attention, especially on the Mac side, where the menu is on top of the screen, not the window, the shortcuts are different, and even worst, the menu do not follow the same conventions! For instance the “About” menu is in the Application special menu, not in the Help menu as on Windows. To achieve that in Java requires the Apple OSXAdapter to call by reflection an API that will not be available on non Mac platforms!

Again I hardly do any user interface usually at work, so this little project was overal a good experience to me, and now the users have begun to play with it it is soon to become even more interesting!

Update: here is a video of how to chop a loop almost automatically into slices, then how to play it back at a different tempo on the MPC:

Read More

Essential patterns books for today object-oriented developers

The more patterns developers know, the most efficient they become within a team: it only takes one or two words (the pattern name) to communicate a design decision or proposal, instead of 10 mn of explanations. Communication also gets much more accurate and to-the-point (or less fuzzy).

Because patterns often form a pattern language, not only they offer a standard vocabulary but they also help structuring the mind by their relationships: patterns can be related as exclusive alternatives, or rather often-go-together, which is useful.

Patterns are not always supposed to be “tricks” to learn, or extra complication to introduce to a design; indeed even obvious and uninteresting pattern are worth reading in books, just for the social advantage of being able to reference them. Going further, sometime you can just go to the book to find out which is the pattern that you just did without knowing its name…

Design Patterns: Elements of Reusable Object-Oriented Software (Addison-Wesley Professional Computing Series)
1.  Design Patterns: Elements of Reusable Object-Oriented Software (Addison-Wesley Professional Computing Series) by Erich Gamma et al.
The most essential book, a definitive must-have. Every experienced software developer must know these 23 design patterns.

Analysis Patterns: Reusable Object Models (Addison-Wesley Object Technology Series)
2.  Analysis Patterns: Reusable Object Models (Addison-Wesley Object Technology Series) by Martin Fowler
The essential complement to the GoF, to extend the benefits of patterns from design to analysis (closer to the problem to solve in the domain). Each pattern will not necessarily teach you a new solution, but will always give you have a standard name for each solution, which is already worth the book.

Domain-Driven Design: Tackling Complexity in the Heart of Software
3.  Domain-Driven Design: Tackling Complexity in the Heart of Software by Eric Evans
A book that can change the way you deal with software. Considering the domain as the main driver of the design is so powerful an approach! Works best together with the analysis patterns.

Patterns of Enterprise Application Architecture (Addison-Wesley Signature Series)
4.  Patterns of Enterprise Application Architecture (Addison-Wesley Signature Series) by Martin Fowler
Other analysis patterns to solve many technical problems, useful complement to Analysis Patterns.

Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions (Addison-Wesley Signature Series)
5.  Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions (Addison-Wesley Signature Series) by Gregor Hohpe
Very complete pattern language (both test and visual vocabulary) about messaging, will improve the communication within a team a lot, both in efficiency and in accuracy.

Pattern-Oriented Software Architecture Volume 2: Patterns for Concurrent and Networked Objects
6.  Pattern-Oriented Software Architecture Volume 2: Patterns for Concurrent and Networked Objects by Douglas Schmidt
Important book, more specialized toward optimized low-level problems (web servers…). often quoted. The other volumes are less relevant for today software development on modern languages or virtual machines.

Patterns in Java: A Catalog of Reusable Design Patterns Illustrated with UML, 2nd Edition, Volume 1
7.  Patterns in Java: A Catalog of Reusable Design Patterns Illustrated with UML, 2nd Edition, Volume 1 by Mark Grand
The book I discovered design patterns in, quite affordable, but some colleagues do not like it that much.

Read More

Systematic combination of subpatterns generates design patterns

Composite patterns, such a the Bureaucracy pattern, are patterns built by the composition of other “smaller” patterns. However even usual design patterns can be considered composite patterns made of smaller subpatterns.

The goal is therefore to find out which are the main subpatterns that enable to reconstruct as many design patterns as possible.

The subpatterns

From an early analysis I believe that four subpatterns form the foundation of many GoF design patterns:

  1. Type Hierarchy and its variants (interface, abstract class, non final class…)
  2. Type Set, a set of types with no particular relationship between them
  3. Delegation and its variants (one-to-one, one-to-many)
  4. Allocation (creation of instances) and its variants

The experiment

To validate this proposal, I have coded a small experiment to generate every combination of two subpatterns out of (1) and (2) plus one relationship between them out of (3) and (4), or every combination of one subpattern out of (1) and (2) plus a relationship of (3) and (4) to either itself, or in the case of (1), between a super type and a subtype or the other way round.

For each generated combination I have automatically generated its corresponding class diagram, and grouped them together into one SVG document, converted into PDF using Inkscape. The resulting picture is available here, and you can see a partial preview below:

combinations_thumb

Results

The interesting finding is that this simple combinatorial method re-discovers 11 well-known design patterns (in the reading order of the picture):

  • Template Method (delegation to self, expecting a subtype to provide the service)
  • Composite (Considering a one-to-many delegation) or Decorator / Proxy (one-to-one delegation)
  • Prototype (creates instance of this type)
  • Bridge (one Abstraction hierarchy delegates to another Implementor hierarchy)
  • Abstract Factory (one Factory hierarchy creates instances of another (or several others) Products hierarchy)
  • … skip 4 next …
  • Strategy or State or Builder (some client delegates to some hierarchy)

Note that there are several cases where we could see the Factory Method, Adapter or Facade patterns. This would lead to some 13 design patterns out of the 23 in the GoF book.

Discussion

It is obvious anyway that the four subpatterns used here are not enough to rebuild the full set of the 23 design patterns. The Command pattern is unique in its use of a separate invoker, and the Chain of Responsibility is clearly about how handlers self-assign a given task without any centralized management. In these two examples however, the unique characteristics is not in their structure but rather in their dynamics. Sequence diagrams would be much more relevant to convey that kind of information.

The full test runs in one go in a fraction of second. The source code is available here: patternitygraphic_src, the code of the experiment is in CombinationTest.

EDIT: the plain SVG file that was generated is also available here for download:

Read More

New: Java API for UML diagrams

As part of the Patternity effort, I spent some time creating a simple Java API to generate UML diagrams programmatically from Java, in SVG format.

This small API called for now Patternity Graphic is working and available here: patternitygraphic_src as a source Zip (alpha release of course).

It can render small class diagrams with hierarchic, flow and radial layouts, and arbitrary sequence diagrams with unlimited nesting of method calls and embedded comments. My focus was to support the subset of diagram elements and capabilities required to display patterns occurrences.

Here is a sample sequence diagram with a nice call stack:

sequence1

And here is a class diagram for a simple dummy hierarchy:

hierarchy

Boxes and links have various styles, defined in a template.svg template file, here is a random display of the boxes styles:

boxstyles

Apart from unit tests there is no documentation. If you are interested to reuse that please contact me for help. The Zip was exported in Eclipse with the project Export… function, and the project requires Commons Collections. Svg diagrams can be converted into images using Batik.

Other projects you might consider to generate UML diagrams: UMLGraph, modsl, umlspeed, jsigner, MetaUML, and of course GraphViz.

Any feedback appreciated!

Read More

Patternity is back!

After my initial attempt at doing something useful and automated around design patterns, I started working again on a brand new version of a pattern-aware tool: Patternity.

No more code generation, the focus is now on the generation of documentation artifacts (UML class and sequence diagrams, reports, enhanced Javadoc…) from the source code annotated with explicit pattern occurrences declarations. More like a research project, the goal is to investigate how a tool can be valuable for developers by being aware of the pattern and their occurrences in the source code.

Roadmap

Challenges

Unlike the initial tool I did in 2002 that was really basic, there are many challenges and concerns to be addressed for a tool to deal with pattern in a clever way:

  1. Patterns variants: a pattern can be realized in the source code in many different ways, while still being the same pattern. For instance many patterns rely on polymorphism,which in practice can be achieved with an interface, an abstract class or just a non-final class. Many patterns also use some form of delegation, typically through an association (member field), but the pattern still holds if the delegation occurs through a lookup mechanism.
  2. Representation of patterns: creating a patterns database of a priori knowledge about patterns, including their static and dynamic aspects in a formal way that a tool can interpret – for instance to generate diagrams. Such representation must also be small enough to be feasible manually (of course only once).
  3. How to declare patterns occurrences within the code without interfering with the developer flow of work: easy and logical annotation syntax, good defaults values, code completion in IDE.
  4. How to generate useful artifacts: documentation class and sequence diagrams, reports…

Pattern metamodel

An analysis of a pattern metamodel (points 1 and 2 above) reveals other concerns that add up to the task:

  • Occurrences: What is a pattern occurrence in the code? How many occurrences of the same pattern can be considered the same occurrence? It sounds obvious that a Strategy class and all its subclasses are indeed one same pattern occurrence, but this is a priori not true for the subclasses of an Immutable class (I take a very wide definition of patterns that includes many idioms and other UML-like stereotypes).
  • Classification: Patterns usually couple a Problem (or Intent) and a Solution for it within a Context; how to create the most useful classification of patterns? (I tend to favour a classification by Problem, but this means a SecurityProxy will probably not be related with a VirtualProxy, which is not very intuitive)
  • Identification: How to identify a pattern occurrence? This is useful so that a declaration of a pattern occurrence can reference another pattern occurrence as a member part of it, just like the Bureaucracy pattern is composed of a Composite, a Mediator, a Chain of Responsibility and an Observer.

Pattern declaration

Declaration of pattern occurrences in the source code (point 3 above) also has its issues:

  • Syntax: Definition of a good syntax, easy to grasp with as little explanation as possible is hard
  • Consistency: many patterns introduce additional elements (we can call them active participants) around existing elements (passive elements) that must not know about the pattern. For instance in the Decorator pattern, the Decorator participant (role) participates actively in the pattern, whereas the decorated element should NOT be touched at all, which means that the source file for the decorated class should not be touched in the version control when adding the pattern.
  • Where to declare: in the source code, using Javadoc tags for classes or methods, or in an external file when this is more convenient (e-g to annotate third-party libraries).
Example of a declaration of a Builder pattern occurrence
Declaration of a Builder pattern occurrence

Generation of documentation artifacts

Generation of artifacts (point 4 above) from both the pattern occurrence declaration and the a priori knowledge about the pattern in the pattern database also yields its own challenges:

  • Reuse, adapt or create a Java API to generate diagrams
  • Find out a logic to interpret pattern data into diagrams or other reports
  • How to deal with huge code bases: use ellipsis, continuation marks and move details to addendum to reduce the size of a diagram

Discussion

Why use patterns for documentation?

Patterns can store pre-digested documentation as “templates”, either textual or visual (diagrams); then for each actual pattern occurrence these templates can be “evaluated” to generate real and complete documentation artifacts. When we want to create useful documentation, the need for developers to inject design information in addition to the information that is already present in the code base can therefore be reduced, since a significant part of these additional information can be factored out and stored once into the patterns metamodel. I expect that patterns are a convenient concept to encapsulate reusable design information and how it can be used, however this has still to be demonstrated in practical use.

I expect that patterns can help create better diagrams than usual case tools, just because patterns know more about the design: knowing that the Bridge pattern is made of type hierarchies (to render vertically) and a delegation betweem them (to render horizontally) makes it easy to draw its class diagram this way:

Generated class diagram for the Bridge pattern
Generated class diagram for the Bridge pattern

Experimental validation

Possible validation of the utility of the tool can be:

  • Design documentation reconstitution: on a well-known and well-documented Open-Source project in Java, annotate the source code with pattern occurrences declarations, then generate a documentation. By comparing this generated documentation with the official documentation of the project one can manually assert the relevance of our approach
  • Maintenance experiments: similar to this study.
  • From the sole pattern database, generate default documentation for each “default” (generated) pattern occurrence, and compare with the patterns books, the more similar the better.

Future work

We could imagine several other potential benefits from using a pattern-aware tool:

  • The requirement to explicitly declare each pattern occurrence while coding also leads to a more motivated design, where each design decision has to be deliberate rather than more or less random or automatic. For beginners, this also represents an incitive to open the books more often to lookup “what is the pattern I am trying to do right now?” because of the need to document it.
  • Provided that the tool can link a pattern with the Problem it is supposed to address, the pattern occurrences can then trace back to their Problem, and from there, link to other alternative patterns that could have been used as well. This could be valuable to do design-level refactoring.
  • The explicit knowledge of the pattern occurrences in the code base can also give insight to configure other tools: for instance, since the patterns know what participant is supposed to know or not the other participants, this knowledge could be used to configure Jdepend automatically.

Please let me know your ideas, remarks or scepticism on this topic!

The official Patternity website still presents the old version; I expect to update it when there is good progress on the new version, however the new source code will be very soon under the same Sourceforge CVS.

Read More

Choosing good names for your Java classes

With Object-Oriented programming we often have many classes, therefore it is really important to name them well.

It’s amazing how I can spend so much time searching for good names for classes, and I do think it is worth doing it well, after all naming is all about making the code easy to read and to understand, which is a major concern in professional programming.

However it is not easy to find good names, and by the way what does “good” naming means ? I claim that a name is good when most people understand it the same way. This gives already a valuable advise to check a name: ask your colleagues what they think of it, or what they would suggest instead. In pair programming, this is obviously always the case, and this sure helps.

But how to find good names in the first place ? First the domain analysis gives good names, because they are names everybody agrees on [1].

Then whenever you use design patterns (or analysis, UI or J2EE patterns), these patterns suggest rather standard prefixes or postfixes for your classes and methods names. For example, if you implement the State pattern, one would expect classes with names like “MyDomainThingState”. Of course this is not a rule, but if you have no good reason not to do this way, you’d better follow the most standard way.

Also, any convention or API that is well-known can be used as a naming guideline, such as the Java API, Commons Collections and some major open-source projects. Any Iterator must be called “SomeIterator”, and a class that purpose is to filter objects is a “SomePredicate”. Naming interfaces that define a capability with “SomeCapability-able” is a very common usage, as well as the use of plural to name a class that operates on a type hierarchy such as Collections (note the plural) that operates over several Collection instances.

Of course Hungarian Notation should be avoided (do not prefix interfaces with “I”) as nobody should ever care that a type is an interface or not to use it the same fashion, only the factory has to know about this implementation detail.

Some words do not mean anything precise, like “data”, “object”, “wrapper”… As a result they do not bring any benefit, they are just in the way. Just try to get rid of them or replace them with words from the domain (with Rename refactoring this is now very easy) and you will be surprised of the level of expressiveness you gain.

Often you think of a name, but for many reasons you cannot use it: maybe you already used it to mean something else, or it suggests something wrong to some people, or it does not suggest anything, or you really do not like it… Then I very often use an online dictionary and a thesaurus to find synonymouses and related words.

A random search in a web search engine is also a good way to go in-depth in the semantic context of a name, in order to find similar and related words that may be used for your naming. This is particularly relevant in specific domains, like finance, where dictionaries are not up-to-date or relevant. By seeing words already used in their context, you can use them more accurately. For example, in finance, we can talk a a group of products as a Package, a Bundle, or a Strategy. The latter is not good because it could mislead to the Strategy pattern. A google search only could help to choose Package, or Bundle, according to the very case you are dealing with.

Package names also help in this topic. Do not forget a class does not have to tell everything in its name, as its package name is part of the actual name and has the purpose to give a context to the short class name. As a consequence, it is not a problem to have the same short class name several times in a project, as long as they are not used together too often. Typically if you have an abstract factory of two families of things, each thing in each family can have the same name, in a dedicated package.

[1] See Ubiquitous Language, by Eric Evans – www.domaindrivendesign.org

UPDATE: An interesting reader’s comment have been destroyed when cleaning spams: this comment suggested to use Eclipse ctrl-shift-t/ctrl-shift-r to see lists of existing class names. Apologises for that.

UPDATE: A class name can reflect what the class really is, or what it is used for. In many cases naming a class according to what it is makes its more reusable, in which case the instance name (field of variable name) tells its purpose for the particular use.

Initially published on Jroller on Thursday April 27, 2006

Read More

Disposable code generation works great !

In a recent project I was asked to parse massive XML document from a third party provider. We had two problems: the xml document definition was very massive, with about 120 groups of different elements, leading to a total of around 1500 different elements to parse into java objects. The other problem was that our only documentation was a massive Word document that described the Xml format using plain English and some rather consistent tables.

Fortunatly the Word document was rather consistent. Each table had a title, and a list of attributes, with their name, type and a comment. Names were ugly UPPERCASENAMEALLTOGETHER. Titles contained a name, with the XML element name within parenthesises: OVERALCREDITSCORE (XYZ78).

We had chosen using Jibx tool to parse Xml (also to generate Xml in other parts of the application) for efficiency reasons, since it is really lightning fast, and very flexible to map any XML structure into Java structures. Jibx requires to write a custom XML mapping file, and obviously we also had to create the Java classes to map to.

The total amount of work was huge: with 120 groups of 12 XML elements to map into 120 Java classes of 12 fields each, wa had to create the 120 corresponding Java classes, and the mapping file with 1500 mapping instruction (from XML element to Java class attribute). I could not imagine doing this by hand, this is horrible work even for a trainee :)

So I copy-pasted the Word document into Excel to convert it into a coma-separated file, fixed the little inconsistencies, then wrote a rustic parser to extract the XML meta model, using some dumb rules such as: “if the cells 3 and 4 are empty then it is a value from the enumeration of possible values”, “if every cell is set then it is an element”… Even the parenthesises were of interest to tell the enclosing element name ! Relying on such stupid criteria seemed frightening, but it worked, and worked quite well !

Then using a simple Java metamodel (class, field, constants as enumerations) and some dedicated Visitors I generated the binding file, the DtD, the java model, a sample XML document to use for testing… in 2 seconds. The complete work including testing took 2 days; I was happy the project manager trusted me on this, he could have decided it would not work and refused me to do it…

I havent told you how I converted the ugly UPPERCASENAMEALLTOGETHER into correct Java naming conventions; using some short business-dedicated dictionary of words, say {UPPER, CASE, NAME, TOGETHER ,ALL…}, a function tries to recognise the words from the dictionary inside the ugly names in order to split them into relevant parts for further camel case naming conversion. It did not work ok 100% of the time, but after a few tries, just add or remove words to solve conflicts, it did the whole job automatically !

Such a disposable, dedicated code generator works great, I dont care I wont reuse it, as long as I get the work done quickly…

Note: the design is actually very common and reusable: an object model (Composite pattern), a parser (Builder pattern) and some code generators (Visitor pattern).

Initially published on Jroller on Tuesday March 29, 2005

Read More