Development Best Practices
Contents
Values Principles Practices o o o o o o o o o o Testing Naming Conventions Client and Server-Side Architectural Patterns ImsCommonsUtil Database Access Dependency Injection/Inversion of Control Business (Domain) Objects GUI Refactoring Core Java

Values
Simplicity Use the simplest design for the current functionality; don't try to anticipate tomorrow's needs. Code should be easy for a new developer to understand (or yourself a year later). Don't optimize for performance unless there's empirical evidence that it is needed. Be wary of building or using frameworks that make the application harder to understand. If you do need a framework (e.g. Spring for dependency injection), make sure the application's business logic isn't tied to the framework in any way. Maintainability Good naming is crucial. You should be able to read the code aloud, and a person listening to you should be able to understand what the code you are reading does Put responsibilities in the right place. Enforce a clean separation of the application's layers. For example, the UI code should not know anything about the database structure. Use well-known patterns and common idioms for the language. Maintain consistency at the module, application, and team level. There's always more than one way to do something, but doing it consistently is more important than finding the absolute best way.

Information Classification: Limited Access

Refactor your application code aggressively to maintain design quality in the face of changing requirements. Testing Use automated unit and regression tests to verify business functionality, minimize defects and enable safe refactoring Communication Developers, QA testers and business analysts must communicate constantly to ensure that the correct functionality is built. All parts of the system should be known by at least two members of the team. Knowledge silos should be identified and rectified. The project goal is to add business value (play to win), not just holding the line or going by the book (play not to lose).

Principles
Keep methods and classes small, simple and short Classes and methods should be short and focused on specific tasks. Breaking down complex functionality into concise, well named methods allows future developers to maintain and easier understand application logic. Smaller methods will lead to an increase in the number of methods within a class which can reduce maintainability therefore it is important to keep classes small. Greater than 500 lines of code in a class is cause for concern, greater than 1000 will require refactoring to delegate that logic into collaborator classes.

Code should be readable and self-documenting Readability of code includes well named classes, methods and variable (See naming convention section). Readability also includes a consistent approach to adding functionality within an application. Reusing an existing pattern is favored over introducing a new, even slightly better, paradigm. It should be a team decision to move away from existing practices, once decided existing code should be converted to avoid multiple architectures in the application. The code itself is the ultimate documentation of any system. Unnecessary javadocs/comments clutter the codebase and quickly become out of date. Extracting methods and naming them explicitly often replaces the need for comments. Comments, used sparingly, should describe why something is being done, not what it is doing. Class methods ideally should be responsible for either invoking a sequence of other methods (where the actual work is performed) or performing a specific piece of functionality. Avoid having methods that have both responsibilities. This leads to layered code both at a component and class level.

Information Classification: Limited Access

Avoid creating/using large frameworks Frameworks should NEVER be created during the initial implementation of functionality. Frameworks often seem an easy way to add repetitive functionality, but in reality frameworks tend to limit the flexibility of an application. New functionality which does not fit into the existing framework causes unnecessary complication and often proves to be impossible to implement without a significant rewrite.

Address biggest risks first, while keeping business priorities up front. If something is going to fail, the earlier it fails the better. Agile development replaces a large upfront design phase with coding earlier in the process. Real world knowledge obtained during early development proves more valuable than developer’s best guesses during design meetings. Sometimes it is necessary to re-implement components based on lessons learned, typically in a way different than originally expected. In order to reduce the amount of work required to refactor the application, it is important to prioritize development that has the highest risk factor as early as possible.

Favor Immutability Immutable objects cannot change their state once created. This is accomplished in part by using the final keyword (in java). Utilizing immutable objects makes the source code easier to understand since objects cannot be modified downstream by subsequent logic (intentionally or accidentally via side effects). Another major benefit is that all immutable objects are inherently threadsafe. Declaring an object’s members final does not always make it immutable -- an example would be a collection where the internal elements inside that collection can still be manipulated. In order to make that field immutable you would need to create the collection using Collections.unmodifiableCollection() in addition to the final keyword. It is important to ensure all sub-objects continue that chain of immutability to be effective. Final is sufficient for primitives but further care is required for generic objects. Always start out with immutable objects when designing a system or feature since it is often difficult to retrofit later. See the Business/Domain Objects section below for examples.

Composition over Inheritance Composition promotes reuse as opposed to a more rigid class hierarchy. Inheritance allows users to extend functionality in a manner that the original developer possibly did not intend for. Overriding methods in sub classes complicates the program flow and makes code dependent on implementation details of another class. Large class hierarchies can require execution-time debugging to understand the code path taken, reducing the readability of an application.

Information Classification: Limited Access

Separation of concerns (Modularity) Clearly defining the responsibility of classes and modules without significant overlap promotes reuse by having a narrow purpose not dependent on other functionality (Decoupling). Encapsulating the details of component allows the caller to avoid implementation details. For example, the code to send an email should not reside with a business logic component but in its own separate service class which can be leveraged elsewhere.

Avoid duplication of logic. Code duplication is a sign that refactoring is required. Duplicated code often leads to bugs as one location can be updated without the developer realizing a modification is required elsewhere. By encapsulating the logic in a class we are able to leverage working and tested code.

Practices
Testing
Test Driven Development (TDD) One of the most important parts of our development process is Test Driven Development (TDD). TDD entails: 1. 2. 3. 4. 5. create a failing test run the test to verify it fails write some code to make the test pass run the test to verify it passes repeat process

By writing the test first, it ensures that the code being developed is testable. When tests are not written first, the code can be difficult to test and in many cases tests are never written causing a shortage in test coverage. One TDD practice we use while pairing is to have one developer write a test and the other developer writes the code to make the test pass. They switch roles for the next test and repeat. This helps to keep both developers equally involved and promotes communication. Unit Testing A unit test should test the smallest testable unit of code; this is usually one scenario for a method. Since a unit test should only test one scenario for the smallest testable unit of code, dependencies should be mocked out. In order to mock out the dependencies, dependencies need to be injected (see Dependency Injection/Inversion of Control) rather than instantiated in the class that's being tested. This

Information Classification: Limited Access

is part of writing code in a TDD style to make sure the code is testable. We use mock libraries (such as Mockito) to mock out these dependencies and to make them behave in the expected manner. A simple unit test should do the following when applicable: 1. 2. 3. 4. 5. 6. initialize test input data create mock objects and set expected behavior of mocks initialize class that is being tested and inject input data and mocks when applicable invoke method that is being tested and inject input data and mocks when applicable assert the return value from the method for the scenario verify mock object behavior (Mockito)

In order to facilate the above, we use standard comments in all of our unit tests when applicable: // // // // // // initialize variable inputs initialize mocks initialize class to test invoke method on class to test assert return value verify mock

Some unit test development best practices: In general, each test case should cover only one case. Only provide the parameters that your test case needs to pass. If your test does not need a parameter use null. In general you should not mock POJOs. Instead, instantiate an instance. Do not mock every parameter unless it a) is needed for the test case to pass and b) is not a POJO. (see rule above) Test cases should be self-contained and should not rely on globally scoped/instance variables. They shouldn't interact with other tests, and the order that the tests run in should not matter. Add ‘throws Exception’ to your test method template signature. This helps to discourage explicit exception handling in tests. Avoid putting assertions inside of loops or threads. Call assertEquals(one, two), rather than assertTrue(one.equals(two)) or assertTrue(one == two). This will provide a better error message if the assertion fails. Avoid the use of setup & teardown methods as much as possible (this includes @BeforeClass, @Before, @AfterClass, @After). These can make tests harder to understand and refactor. Whenever a defect is found, a failing test that demonstrates the defect should be added before fixing it. Avoid class hierarchies in test classes. The rules for duplicating code in tests are slightly less stringent than the rules for production code.

Information Classification: Limited Access

Mocks Mocks are test doubles that simulate objects' behavior via setting expectations on what methods are called and what values are returned from those methods. We use mock objects in unit tests to limit the scope of the test to the immediate method being tested, but still verify the interaction with its dependencies. Please see Dependency Injection for more information on how to inject dependencies. There are many mock libraries to assist in creating mock objects. Currently, our preferred mock library is Mockito. For more information on Mocks and test doubles, see Martin Fowler's article 'Mocks Aren't Stubs' http://martinfowler.com/articles/mocksArentStubs.html Unit Test Naming Conventions Unit Test Classes should be named for the class they test and end with ‘Test’. Ex. InvestorTableModelTest tests InvestorTableModel Your unit test class should be in the same package as the class it tests but separated into a separate ‘test’ directory structure. Each test method should begin with ‘test’. Ex. testGetValueAt would test the method getValueAt When numerous test cases are needed for a single method append the condition to the test name: Ex. testGetValueAt_withInvalidColumn … testGetValueAt_nullData Examples of TDD, Unit Tests and Mocks Given the following class: public class Service { private final Repository repository; public Service(Repository repository) { this.repository = repository; } ... } Let's say we want a new method to compute some value based on data retrieved from the database via the repository. 1) create a failing test public class ServiceTest { ... @Test public void testCompute() throws Exception { // initialize variable inputs int id = 123 int quantity = 1234;

Information Classification: Limited Access

int factor = 2; MyData myData = new MyData(quantity, factor); // initialize mocks Mock repository = mock(Repository.class); when(repository.fetchData(id)).thenReturn(myData); // initialize class to test Service testClass = new Service(repository); // invoke method on class to test int returnValue = testClass.compute(id); // assert return value assertEquals(2468, returnValue); } } The method compute needs to be created in Service in order for the test to compile. This initial method creation is just to make the test compile, so it is stubbed out with no logic or just a return statement. IDE's can help you do this very easily. public class Service { private final Repository repository; public Service(Repository repository) { this.repository = repository; } public int compute(int id) { return -1; } } 2) run the test to verify it fails (the above clearly fails as -1 != 2468) 3) write some code to make test pass public class Service { private final Repository repository; public Service(Repository repository) { this.repository = repository; } public int compute(int id) { MyData data = repository.fetchData(id); return data.getQuantity() * data.getFactor(); } } 4) run the test to verify it passes (the above should now pass)

Information Classification: Limited Access

5) repeat process Write more tests for more scenarios. For example, what should happen when the repository returns null. Note that we handle testing expected exceptions in two possible ways: 1. Assert the exception message after catching the correct exception (see below) 2. Use the 'expected' parameter in the @Test annotation e.g. @Test(expected=RuntimeException.class) public class ServiceTest { ... @Test public void testCompute() throws Exception { // initialize variable inputs int id = 123 int quantity = 1234; int factor = 2; MyData myData = new MyData(quantity, factor); // initialize mocks Mock repository = mock(Repository.class); when(repository.fetchData(id)).thenReturn(myData); // initialize class to test Service testClass = new Service(repository); // invoke method on class to test int returnValue = testClass.compute(id); // assert return value assertEquals(2468, returnValue); } @Test public void testCompute_whenMyDataNotFound() throws Exception { // initialize variable inputs int id = 123 // initialize mocks Mock repository = mock(Repository.class); when(repository.fetchData(id)).thenReturn(null); // initialize class to test testClass = new Service(repository); // invoke method on class to test try { testClass.compute(id); } catch (RuntimeException re) { // assert return value assertEquals("Data with id [123] was not found", e.getMessage()); } }

Information Classification: Limited Access

} Make the test pass public class Service { private final Repository repository; public Service(Repository repository) { this.repository = repository; } public int compute(int id) { MyData data = repository.fetchData(id); if (data == null) { throw new RuntimeException(String.format("Data with id [%s] was not found", id)); } return data.getQuantity() * data.getFactor(); } } End-to-End / Integration Testing Most of the projects at IFS have end-to-end/integration tests. Project-level end-to-end tests test and verify that all components within the project interact as expected; this includes the database. If the application connects to external applications, these may be mocked out if needed. Like unit testing, some end-to-end tests are created at the beginning of working on a story to test the expected behavior of a story. Because the implementation of the story has not been started, this will create a failing test. When the implementation is complete, the end-to-end test should pass. Because you cannot guarantee data in a shared development database, all the data required to run the end-toend test is set up at the beginning of the test. Unlike unit testing, not all scenarios need to be tested for end-to-end testing. End-to-end tests test and verify that the behavior of all the components assembled together work as expected. Because end-toend tests use an assembled application and a database (if applicable), these tests take much longer to run than unit tests. Therefore, end-to-end tests are created to test functionality that cannot be fully tested in the unit tests. For example, an end-to-end test would pass input into the entry point of an application and verify that the correct data is stored into the database. So, an end-to-end test would pass trade input data into a trade capture application and verify that the trade has successfully made it to the database. Or pass bad data into the trade capture system to verify the application throws validation errors. We would not need to test every possible validation error, but test every major path through the application.

Information Classification: Limited Access

Continuous Integration (CI) We use the practice of Continuous Integration to decrease the number of bugs due to code integration, but also to have a releasable build after each story. Similar to the practice of 'release early and often', CI allows developers to 'integrate early and often'. When developers finish a story, they commit the code for that story into the baseline repository. Each commit triggers a CI build server (e.g. Jenkins) to build the project and run all the unit tests. To make this practice successful, developers should commit after each completed story, the tests should run in a short amount of time, and each build should produce a releasable version of the product. For more information, see the Martin Fowler article on Continuous Integration located at http://martinfowler.com/articles/continuousIntegration.html

Naming Conventions
Good naming is central to making maintainable software. To start with, follow the standard java naming conventions for capitalization, etc. (http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-135099.html#367). Names should be carefully chosen to make the code as easy as possible to understand. They should be as long as needed to sufficiently convey the purpose of the variable, method or class, but not longer. Single-character names should be avoided except for obvious idioms like loop counters. for(int i = 0; i < elements.size(); i++) { // OK String x = "ABC"; // BAD Do not abbreviate words that make up part of a name, except for commonly used acronyms and initialisms: int contractQty = 4; // BAD int contractQuantity = 4; // OK this.jdbcTemplate // OK Names should make sense for the abstraction level of the place where they are used, and should preserve encapsulation. For example: // OK, name encapsulates logic. boolean isValid(Contract contract) { return contract.getExpirationDate().after(getCurrentDate()) && contract.getPrice() > 0; } // BAD, name leaks implementation details boolean isUnexpiredAndPriceIsGreaterThanZero(Contract contract) {

Information Classification: Limited Access

return contract.getExpirationDate().after(getCurrentDate()) && contract.getPrice() > 0; } boolean isValidContract = contract.isValid(); // OK boolean isUnexpiredAndPriceIsNotZero = contract.isValid(); // BAD, breaks encapsulation of isValid() method Elements of Java Style is a good resource for further reading on naming.

Client and Server-Side Architectural Patterns
We approach both the client and server side architectures of our applications using a layered approach. Each layer should have well-defined responsibilities, and we avoid leaking those responsibilities between layers. The interfaces between the layers should involve strongly typed java business objects, rather than something more weakly typed like Maps or Object. Here are the common layers that are used in the majority of our applications: 1. Client Presentation layer: This layer is responsible for gathering information from the user and displaying information to the user. As much as possible, business logic and validation logic should not be in this layer. Any logic should pertain to data-entry requirements, and managing the actual interaction between widgets in the application. See the GUI section for more information on how we like to structure this part of the applications. 2. Client-Server transport layer: The transport of data between the client and server is handled in this layer. The implementation will be provided as a part of standard library code in ImsCommonsUtil. Both the client and server code should not know anything about how the data is being transported between the two and should just interact via well-defined type-safe java interfaces. This is not applicable for web and cloud applications. 3. Service layer: On the server, all business logic should be contained within coarse-grained services. This includes such things as non-trivial calculations, validation, and general business logic specific to the application. The service layer receives requests from the client, interacts with the Persistence layer via well-defined interfaces and returns data to the client in the form of strongly-typed business objects. If a given business process is of sufficient complexity, the service layer may utilize other server-side components that encapsulate the business logic. These components would also be considered a part of the service layer. 4. Persistence layer: The persistence layer is responsible for translating to and from business objects and the underlying data store (usually an RDBMS, but sometimes other external data stores as well). Any logic contained in this layer should be concerned only with this translation. Application business logic should not creep into this layer. The only layer that should interact with the persistence layer is the service layer.

Information Classification: Limited Access

ImsCommonsUtil
ImsCommons is a collection of generic functionality that is useful among all projects at IFS. Please review ImsCommons to ensure you are not recreating already existing code. Before adding new code into commons an incubation period is required in your local application to ensure that it is relatviely bug free. Please contact your team's technical lead before checking in new code. Functionality includes: Application Launcher ImsScheduledExecutorService JDBC: ImsJdbcTemplate JMS: ImsJmsTemplate PasswordMatrix Metrics Utilities: o o o o o o o o BigDecimalHelper CalendarDate CollectionHelper CsvHelper DateHelper ExceptionHelper ImsProperties StringHelper

Database Access
ImsJdbcTemplate (from ImsCommonsUtil) ImsJdbcTemplate, similar to spring framework's JdbcTemplate, tries to simplify calls to the database by only exposing a subset of methods. There are a few implementations that can be chained together to obtain desired behavior. An example spring framework configuration (taken from TmanServer):

Information Classification: Limited Access

Information Classification: Limited Access

Connection Pool A connection pool is used to manage connections to a DB and to enhance the performance of executing commands on the DB. Currently we have standardized on the C3PO jdbc connection pool ORM libraries (i.e. Hibernate) We have decided against using ORM libraries for the following reasons: ORMs are an anti-pattern 1. It initially appears to be beneficial, but in the long term has more bad consequences than good ones. We have a legacy application with a non-reproducible race condition due to Hibernate. 2. An alternative solution exists that is proven and repeatable Design of Caliber database makes it hard to use an ORM. no control over sql bloated software library No business logic in SQL or stored procedures We should always have business logic in our java code so that unit tests can be written for it and the logic is easier to follow when in the code. There is also a cloud directives around this concept o Move Business Logic to a Rules Engine and/or Java

Dependency Injection/Inversion of Control
When one class uses an instance of another class to do some work, we use the dependency injection (DI) pattern in order to separate a class's interaction with its dependency from the details of how that dependency is provided to it. If you find yourself using either a service locator or a static singleton to access a dependency, or if you are creating the dependency directly in the class that uses it, DI is the preferred alternative. DI makes classes more testable, since dependencies can be mocked without any special code needed in the class being tested. It also encourages a clean separation between architectural layers, and between interfaces and concrete implementations. Often the dependency will be an interface representing a lower-level abstraction (e.g. a repository using a jdbc template). There are two common flavors of dependency injection, constructor-based and setter-based. We prefer constructor-based because it allows the dependency to be declared as a final member, and keeps the class immutable.

Information Classification: Limited Access

Here's a simple example of constructor dependency injection: class Service { private final Repository repository; Service(Repository repository) { this.repository = repository; } Result compute(int id) { MyData data = repository.fetchData(id); // do something with it return ... } } This class can be unit-tested in isolation, mocking the repository which it depends on: int id = 123 MyData myData = new MyData("foo"); Mock repository = mock(Repository.class); when(repository.fetchData(id)).thenReturn(myData); Service testClass = new Service(repository); Result returnValue = testClass.compute(id); assertEquals(expected, returnValue); Applications that use DI need to be wired up at runtime. For a small application, this can be as simple as a Main class that instantiates all the objects, passing them to each other's constructors as needed: public class AppMain { public static void main(String[] args) { Service service = new Service(new RepositoryImpl(new JdbcTemplateImpl(createDataSource()))); service.start(); } } For more complicated applications, we often use Spring Framework to do the wiring. Spring provides additional behavior like lifecycle management (e.g. shutting down resources when the application stops). Application code should not be aware that it is running inside Spring. Except for the main class (or whatever is instantiating the application context), you shouldn't be writing code like the following, which breaks dependency injection and defeats the purpose of using Spring:

Information Classification: Limited Access

// BAD MyClass bean = (MyClass)appContext.get("xyz"); bean.doSomeWork(); Spring should not be needed for unit tests, which should just instantiate the objects being tested and pass in mock dependencies as needed.

Business (Domain) Objects
We model business objects as simple, immutable data classes (see section on immutability). These objects are often used to pass data between services. The class should generally only have getters, equals, hashCode and toString methods. Some exceptions would include methods that only interact with internal data for some trivial transformation or calculation. We usually use the IDE to implement the equals, hashCode and toString methods. Example: package com.imsi.tmanapi; public class Clearer { private final String code; private final String account; public Clearer(String code, String account) { this.code = code; this.account= account; } public String getCode() { return code; } public String getAccount() { return account; } public String getFullName() { return String.format("%s:%s", code, account); } @Override public boolean equals(Object o) { if (this == o) return true; if (o == null || getClass() != o.getClass()) return false; Clearer clearer = (Clearer) o; if (account!= null ? !account.equals(clearer.account) : clearer.account!= null) return false; if (code != null ? !code.equals(clearer.code) : clearer.code != null) return false; return true; } @Override public int hashCode() { int result = code != null ? code.hashCode() : 0; result = 31 * result + (account!= null ? account.hashCode() :

Information Classification: Limited Access

0); return result; } @Override public String toString() { return "Clearer{" + "code='" + code + '\'' + ", account='" + account+ '\'' + '}'; } } Anti-Patterns: We avoid putting business logic in the business object. We also let the business object to be a simple data class and avoid adding loading/saving logic to the class. Example of anti-pattern: package com.imsi.tmanapi; import import import import import import com.imsi.jdbc.ImsDataAccessUtils; com.imsi.jdbc.ImsJdbcTemplate; com.imsi.jdbc.Mapper; com.imsi.tmanapi.repository.GlobalRepository; java.sql.ResultSet; java.sql.SQLException;

public class Clearer { // class member is not final private String code; // class member is not final private String account; public String getCode() { return code; } public String getAccount() { return account; } // setter method public void setCode(String code) { this.code = code; } // setter method public void setAccount(String account) { this.account= account; }

Information Classification: Limited Access

public String getFullName() { return String.format("%s:%s", code, account); } // business logic public void validate(GlobalRepository globalRepository, String client) throws TmanApiValidationException { if (!globalRepository.clearerExists(client, code)) { throw new TmanApiValidationException(String.format("Clearer %s was not found for client %s", code, client)); } } // loading/factory logic public static Clearer load(ImsJdbcTemplate jdbcTemplate, String client) { return ImsDataAccessUtils.singleResult(jdbcTemplate.query(“getClearer”, new Mapper() { @Override public Clearer mapRow(ResultSet resultSet, int rowNum) throws SQLException { Clearer clearer = new Clearer(); clearer.setCode(resultSet.getString("clearer")); clearer.setAccount(resultSet.getString("clearer_accoun t")); return clearer; } }, client)); } // no equals method // no hashCode method // no toString method }

GUI
Swing Most of our UI apps are developed using Java Swing. Our ImsCommonsSwing project is a collaboration of code to support common UI patterns and helper classes. We should not use third party swing libraries or create custom components. We should use the standard Swing widgets as much as possible (JTable, JComboBox, etc). Some widgets have been extended in the ImsCommonsSwing library so those should be used before attempting to provide your own. If you are contemplating extending JTable or a similar class, there is probably another way to implement or you may want to talk to BA to discuss requirements as we should be designing UI in a Swing standard way. Writing custom components makes it harder to test and we know that Swing is

Information Classification: Limited Access

well tested already by the community. It also makes it harder to move between Java versions as new implementations may not be compatible with modified functionality. Action/SwingAction classes One of the nicest features of this library is the use of Actions. Java provides its own event handling, but makes it a bit complicated in the number of types of listeners and event classes and its handing of event dispatch thread vs. swing worker thread. The SwingActions class is a holder of actions which will be fired off when some event happens. The ValueChangeListener is responsible for wiring the SwingActions to the swing component and encapsulates all of the swing listener/event handling logic. For example: JComboBox aComboBox = new JComboBox(); SwingActions actions = new SwingActions(); actions.addAction(new CalculateSomeValueAction()); actions.addAction(new EnableSomeFieldAction()); ValueChangeListener.addListener(aComboBox, actions); These Action classes (i.e. CalculateSomeValueAction) increase the testability of the UI. Each of these action classes should have one general task (in the example case: grabbing some values from the UI, calling the service to make some calculation, and then setting that value onto a field) Example of testing action class: public class CalculateSomeValueActionTest { @Test public void testExecute() throws Exception { // initialize variable inputs BestPracticesUI bestPracticesUI = new BestPracticesUI(); // initialize mocks CalculationService calculationService = mock(CalculationService.class); when(calculationService.calculate()).then(returnValue(calculat edValue)); // initialize class to test CalculateSomeValueAction testClass = new CalculateSomeValueAction(calculationService, bestPracticesUI); // invoke method on class to test Action.Result returnValue = testClass.execute(); // assert return value assertEquals(Action.Result.CONTINUE_PROCESSING, returnValue); assertEquals(calculatedValue, bestPracticesUI.getCalculatedFieldValue());

Information Classification: Limited Access

} } Action classes can also be annotated to specify whether they will run on the @EventDispatchThread or the @SwingWorkerThread. The event dispatch thread is where all event-handling code is executed, whereas the swing worker threads are where time-consuming background tasks are executed. For more info on these two swing thread types see http://docs.oracle.com/javase/tutorial/uiswing/concurrency/index.html ImsCommonsSwing also has a Components class which provides a common way to create swing UI components (JButton, JTextField, JComboBox (with populators), etc) Another useful class is the UncaughtExceptionHandler which, as the name suggests, catches all exceptions which have flowed up the stack and pops up a dialog to the user. A common pattern used in most of our UI applications is the use of ClientContext. This class is extended by project specific classes and usually hold references to remote services. This context class is usually passed around to UI/action classes to gain access to these remote services, dialog manager, window manager, etc. Some other userful classes: DialogManager, WindowManager, SwingHelper, EventDispatchThreadComboBoxPopulator, SwingWorkerThreadComboBoxPopulator Widget/Component classes: TypedComboBoxModel, FormattedTextFieldWithInputValidation, ComboBoxWithWidePopup, AutoCompleteEntryField One of the more painful aspects of Swing UI development is the use of layout managers to lay out the components on the screen. We've tried to standardize on using MigLayout library to try and simplify this task and make it consistent across projects. (See http://www.miglayout.com/) Google Web Toolkit (GWT) https://developers.google.com/web-toolkit/ GWT is an open source set of tools that allows web developers to create and maintain complex JavaScript front-end applications in Java. This is currently the preferred solution when it comes to developing web UIs as it is completely in Java and is therefore highly testable. The Model-View-Presenter (MVP) pattern is recommended for GWT applications as it eliminates the need for a browser and standard JUnit test classes can be created. This pattern also produces a clear separation of GWT UI and business logic and a minimal dependency on GWT implementation.

OSA Web Toolkit (OWT) http://cdt.statestr.com/wp-content/uploads/2011/11/Overview-of-CDT.zip OWT is a State Street library which extends the GWT and GWT-EXT framework and is required for all applications running in the cloud. One of the main benefits of OWT is the tight

Information Classification: Limited Access

integration with cloud services allowing for rapid development . Direct usage of native GWT classes are prohibited in the cloud.

Refactoring
What is refactoring: Refactoring is the process of improving the structure and design of existing code, without changing any of its functionality. It should always be done in the presence of unit tests, to verify that the functionality of the code has not changed. One of our core principles and values is to be always improving our code. "Relentlessly refactor". Refactoring is not re-writing. Refactoring is an incremental process, not a wholesale replacing of existing code. Refactoring existing, well tested code: Refactoring is an iterative process that generally involves two steps : making a small change, then running the unit tests. These two steps are repeated until the code is in the final state. Larger scale refactorings will almost always involve updating existing tests and writing new ones for any new interface points that are introduced. Please see Martin Fowler's Refactoring : Improving the Design of Existing Code for an excellent treatise on how to perform refactorings. Chapter 1 is especially good for showing a concrete example of the refactoring process. Working with non-unit-tested legacy code: Legacy code : "Code without unit tests" Be very careful. There is no safety net in this case. Rely as much as you can on existing automated acceptance tests. If you are adding a small feature to the existing code, or fixing an existing bug, attempt to introduce a shim into the code which allows at least some unit testing of the new feature. If you are having to make a much larger change, it might make sense to rewrite sections of the code to make them testable. Do this only after discussion with QA and development leads, and making sure that everyone is aware that larger changes are happening, and breakages are likely. These sorts of changes should be as small as possible, to limit the regression exposure. Rely heavily on automated refactoring tools. If you are making larger-scale changes to legacy code, be sure that you are replacing the old untestable paradigms with the testable ones outlined in this document. For a more detailed treatment of how to approach working with legacy code, see Michael Feathers' Working Effectively with Legacy Code.

Core Java
Read and internalize the contents of Effective Java, by Josh Bloch.

Information Classification: Limited Access

Minimize thread safety issues by following these practices o o o Use immutable objects for data shared between threads. Use java.util.concurrent tools like ExecutorService for safely assigning work to other threads, rather than creating your own Threads and using wait() and notify() directly. For any class you create, think ahead of time about whether it will be:    A service that might be called from multiple threads -- it should be stateless in most cases, and must be threadsafe. A value object that might be passed around between threads -- it should be immutable in most cases Only ever used from within a single-threaded context -- it can have unsynchronized mutable state if necessary. An example from the JDK is StringBuilder.

Use lazy initialization only where necessary to solve a proven performance problem. It should never be your first choice, because it complicates the code unnecessarily. Factories should be introduced only where they add value. If they do nothing besides calling a constructor, look for a better design. information hiding - don't make fields public. Static final constants are an exception to this rule. Use BigDecimal instead of float or double for any exact decimal amounts (e.g. money). toString should be uses only for debugging and logging. Business logic shouldn't depend on it. Logging: Logs should make it possible to figure out what happened in production when a support issue is raised. Log relevant information whenever control flow enters and exits a component or service -- input parameters, user id, return values. We use log4j for logging. System.out statements should not be present in production code. The ImsJdbcTemplateWithLogging decorator (see database section) will take care of all SQL logging. Use the java enum to represent any fixed set of values that whose members are known at compile time. Note that enums values can have methods and implement interfaces. This can be a good way to organize declarative code in a typesafe, compiler-enforced manner. Always use typed collections -- e.g. HashMap instead of HashMap

Information Classification: Limited Access