Guidelines for software development in projects

This documents describes some guidelines for software development within CLARIN projects. Since such projects generally have a limited temporal scope, and the original developer(s) will often not be available for support outside the context of the project, additional care has to be taken with respect to a number of aspects that factor into the 'sustainability' of a software projects. Please note that obviously all aspects of this guideline will apply in all circumstances, and that these guidelines can be taken as best practices for any software projects.

Documentation

• Make sure that a description of the requirements of the developed software is available. This will often be part of the project description, but this description may not always be sufficiently descriptive. Ideally, functional and technical design documents are prepared and made available.
• Provide a description of the architecture of the software, either in prose or by means of (a) UML diagram(s)
• Provide good quality in-code documentation. Follow the conventions associated with the language, framework or platform that you are using (e.g. use ​Javadoc for Java rather than just inline comments).
• If applicable, document your API, especially if its public facing. There are tools that make this easy, such as ​Swagger (for Java)
• Bundle some basic documentation with your sources 'and' distribution packages. Include at least the following:
  • README (brief project description, preferably with pointers to more detailed information)
  • INSTALL (setup and configuration instructions)
  • LICENSE (source code licencing information)
• Make a wiki page in the ​CLARIN Trac for the software project or make a section for it in another page if that is more appropriate. This page can serve as a hub to find sources and technical, administrative and other information.
• Make use of an issue tracking system, such as the ​CLARIN Trac or the 'Issues' section of a GitHub repository. Make separate tickets for all known issues as well as potential enhancements. Use milestones or priorities to indicate which issues should be addressed first or which features should be included in a single release.

Implementation choices

• If possible, select a programming language that is widely known and already used within the CLARIN infrastructure, an in particular CLARIN's core development team. For applications that run on a server, Java is the preferred language of choice. For web applications front-ends that run client-side, Javascript is used preferably combined with one of the frameworks mentioned below. Scripts could be written in Python or Bash.
• The same applies to any frameworks that you might use to develop your application. The following frameworks are preferred for various programming languages/environments:
  • ​Apache Wicket for Java-based web-applications
  • ​JAX-RS/​Jersey for REST services
  • ​React for Javascript based front-ends
  • ...

Quality and integrity

• Follow the conventions with respect to code layout, naming and project structure/organisation associated with the language and/or framework that you are using. There may not always be 'official' or uniform conventions, but Google has ​style guides for various languages (including ​Java, ​Javascript, ​Python and ​Shell) that generally provide good guidelines. Obviously, the most important thing is to use consistent style.
• Provide automated tests (unit tests) for your source code. Various tools are available to measure the test coverage of your project. ​Cobertura is an open-source solution for Java projects.
  • Run your tests every time you publish code or binaries. You can test locally on every build, or even better set up remote execution of your tests on a regular basis or triggered by commits/pushes using a continuous integration solution that hooks into your versioning control system (such as ​Travis).
• Try to get your code reviewed, either by a colleague or someone else within the CLARIN community. Start the reviewing process early on, as it usually gets exponentially harder to make structural changes to your code base while it grows.
• Make sure that there are no secrets such as passwords, or other environment specific values in your sources. Use external files (e.g. property files or XML documents) to provide these to your software and provide an example of such a file with your code.

Portability

• Maven
• Continous integration
• Docker
• VCS (GitHub)

Resources

• ​CLARIAH Software Quality Guidelines