Third party libraries

External libs/jar files should only be added when it’s extremely necessary, e.g. adding Apache Commons lib in the Android code for the purposes of using classes like StringUtils is undesirable since this may lead to multidex issues coming up unnecessarily. Always check external library license details before including them in the project. If you are not sure about a library licensing interpretation, do not use it.

Code formatting

It is recommended to use the default formatting feature of an IDE, e.g. Android Studio (AS), to format code. This generates consistently formatted code among developers, which in turn prevents unnecessary conflicts when merging code. To format code in AS use Ctrl+Alt+L (Option+Command+L for Mac). For eclipse use Ctrl+Shift+F (Command+Shift+F for Mac). In eclipse, code formatting can be enabled to execute automatically on file save by enabling the feature in Project → Properties → Save Actions.

Code commenting

Do not leave commented out code in the source files. Just remove it. There are some exceptions of course, such as if you're pretty sure it needs to be re-enabled at some point. To make sure you don't forget why that is, leave a clear TODO comment, e.g. "TODO this needs re-enabled when TRUNK-XXXX is fixed." Most IDEs are good at parsing out all TODO statements. When adding comments to the code follow the javadoc guidelines going forward to ensure that any developer can get the code and know what it does (remember we span out throughout the globe).

Exception handling

Use a given platform’s best exception logging infrastructure, e.g in Android, using Log.*  classes is the recommended way of logging exceptions since exceptions logged this way can automatically be captured by crash reporting tools e.g Crittercism, Crashlytics. When creating new exception classes, create an intuitive hierarchy of exceptions within the package they belong, only creating new Exception classes when branching on different types of exceptions within client/webapp is needed (add as needed instead of making extra classes "just in case" for every possible variation). In Android, as a general rule, use the class name as tag and define it as a static final field at the top of the file. For example:

public class LoginActivity {
    private static final String TAG = LoginActivity.class.getSimpleName();

    public myMethod() {
        Log.e(TAG, "error message");
    }
}

VERBOSE and DEBUG logs must be disabled on release builds. It is also recommended to disable INFORMATION, WARNING and ERROR logs but keep them enabled wherever they may be useful to identify issues on release builds. If enabled, make sure that they are not leaking private information such as email addresses, user ids, etc.

Resources

• Best practices for writing readable code: http://code.tutsplus.com/tutorials/top-15-best-practices-for-writing-super-readable-code--net-8118

• How to write testable code: http://www.toptal.com/qa/how-to-write-testable-code-and-why-it-matters

• Code readability test: http://www.clock.co.uk/blog/code-readability-the-5-minute-explanation-test

• Javadoc standards: http://docstore.mik.ua/orelly/java-ent/jnut/ch07_03.htm

Code testing in OpenSRP

OpenSRP adopts Test Driven Development (TDD), which is an evolutionary approach to development that combines test-first development where we write a test before we write just enough production code to fulfill that test and refactoring. It’s one way to think through your requirements or design before we write our functional code (implying that TDD is both an important agile requirements and agile design technique).

Using this process, you write an automated test first, ensure that the test fails, write the code, and then ensure that the test passes. The benefits of the TDD process are that it drives the API and design, provides good code coverage, promotes safe code refactoring, and keeps developers focused on the task.

Generally, following TDD methodology, the developer will:

• Create a feature branch

• Write failing high-level tests that fail and commit (with a well defined commit message) this to the new branch.

• Start working on the implementation code as the code is continuously committed to the feature branch

• When the feature is finished, update and run the tests to make sure they pass

• Merge the feature branch into the release branch

Unit tests

The goal of unit testing is to isolate each part of the program and show that the individual parts are correct. A unit test should address a single point of functionality and should be fast, understandable (by a human), automatic (no human intervention), and isolated from external resources such as a database, file system, web service, and JMS broker etc.

Unit tests are useful in that:

• They allow you to check the expected behavior of the piece(s) of code you are testing, serving as a contract that it must satisfy.

• They also allow you to safely refactor code without breaking the functionality (contract) of it.

• They allow you to make sure that bug fixes stay fixed by implementing a Unit test after correcting a bug.

• They may serve as as a way to write decoupled code (if you have testing in mind while writing your code).

Integration testing

Integration tests address another aspect of testing where we test software modules in realistic production conditions to validate overall functionality. As a white-box strategy, integration testing is aware of internal implementation details. This time, we use a real database, real API calls and mocking is generally discouraged in these tests.

Since integration tests use a real database, extreme care should be taken to make sure that the tests are not set to run on production databases or resources. To handle this a test.properties file should be setup with the test resources definitions and the test build should also be made to fail if not provided with the build environment params. I.e. test builds should always check or automatically switch the properties file to test.properties.

How to distinguish integration tests from unit tests:

• a test uses the database

• a test uses the network

• a test uses an external system (e.g. a queue or a mail server)

• a test reads/writes files or performs other I/O

Server side integration testing

The Spring Framework provides support for integration testing with the Spring TestContext Framework, which lets you write tests for a framework like JUnit. In JUnit, the @RunWith annotation sets a Runner class, which is responsible for launching tests, triggering events, and marking tests as successful or failed

For server side integration testing, use the following Spring TestContext Framework features:

• The @ContextConfiguration annotation is used to load a Spring context from an XML file, for example, @ContextConfiguration("/path/context.xml"). By convention, if an application context path isn’t set, the path is set to [Test- ClassName]-context.xml.

• Spring TestContext caches the application context for better performance. This saves time on each test startup.

• The @DirtiesContext annotation indicates that the application context for a test is dirty and that TestContext should close it after each test.

• Spring TestContext defines a listener API for tests to interact with objects with the @TestExecutionListeners annotation. For example, the DependencyInjectTestExecutionListener class provides support for dependency injection and initialization of test instances. Spring TestContext adds this listener by default and injects field by type, annotated with @Autowired or by name with @Resource.

The following simple example uses these features:

@RunWith(SpringJUnit4ClassRunner.class)

@ContextConfiguration("/path/to/context.xml")

public class OpenSRPIntegrationTest {

  @Autowired

  private OpenSRPObject object;

  @Test

  public void test() {

  }

}

Functional testing

Functional tests focus on the functional requirements of an application, and use the black-box testing strategy. This involves providing input values and verifying output values without concern for any implementation details. Functional testing ensures that the app meets its functional requirements and achieves a high standard of quality such that it is more likely to be successfully adopted by users.

OpenSRP-client (Android)

Functional tests should be setup using Espresso to simulate user interaction using ViewMatchers class, Hamcrest Matchers or the onData method to locate view items.

OpenSRP-server(Java, HTML)

Functional tests should be setup using Selenium to simulate user interaction.

For both server and client apps, if a click on a view results in the creation, updating, or deletion of records in the database, the respective test should test for this change as well. E.g A test for the login page should test that all the required views are visible and respond to the clicks by either displaying validation error messages or navigating to a new screen and also validate that user data is saved in the sharedpreferences or in the local client/server database.

As a good practice and for code reuse and maintainability, all view access code in a given page should be put in a pageobject.

Continuous integration

- mvn test

DC|RA: Migrate to gradle

MK: Remove live server calls from connector and web

[DO NOT MERGE] 63 Remove live server calls from connector and web