Conventies

Commentaar

• Het 'tijdelijk' in commentaar zetten van code is verboden. Over een jaar staat het er nog, en weet niemand meer waarom. Verwijder de bewuste code gewoon. We hebben versiebeheer.
• Commentaar is in het Nederlands. Engels is niet toegestaan.
• Let op schrijffouten en grammatica en maak geen grappen. Schrijf alsof de klant het zal lezen. Uiteindelijk krijgt de klant alles opgeleverd, inclusief de code.
• Verwijs zoveel mogelijk naar de functionele documentatie waar de code bijhoort (Use Cases).
• Werk bij wijzigingen in code altijd het commentaar bij.
• Maak gebruik van JavaDoc macro's: {@inheritDoc}, {@link}, {@code}, etc.
• Iedere klasse (en interface) heeft commentaar.
  • Eerste regel: gebiedende wijs; 1 zin die het doel van de klasse beschrijft.
  • Overige regels (indien nodig): hoe het doel bereikt wordt.
  • @author tags gebruiken we niet. Een auteur suggereert een eigenaar, en die er is niet. Want de code is van het team.
  • @version tags gebruiken we niet. Zie Subversion.
  • @see tags gebruiken we wel. Dit vergemakkelijkt het navigeren door (gerelateerde) JavaDoc.
  • We nemen geen logmeldingen uit Subversion automatisch op in de code. Dat geeft alleen maar problemen met branching.

    Voorbeeld:

    /**
     * Implementeert de {@link ReisdocumentDao} voor Hibernate.
     * <p/>
     * De Hibernate {@link SessionFactory} moet worden meegegeven aan
     * de constructor. Alle acties maken vervolgens gebruik van de
     * huidige sessie. Deze wordt door Spring automatisch geinitialiseerd
     * aan het begin van iedere database transactie.
     */
    public class HibernateReisdocumentDao implements ReisdocumentDao {
        // ...
    }

• Iedere methode heeft commentaar.
  • Eerste regel: gebiedende wijs; 1 zin die het doel van de klasse beschrijft.
  • Overige regels (indien nodig): hoe het doel bereikt wordt.
  • Alle parameters zijn beschreven.
  • Het eventuele resultaat is beschreven.

    Voorbeeld:

    /**
     * Zoekt een reisdocument op sleutel.
     *
     * @param id De sleutel van het reisdocument,
     *           mag niet {@code null} zijn.
     * @return Het reisdocument behorend bij de sleutel,
     *         of {@code null} als het niet bestaat.
     */
    public Reisdocument findReisdocument(String id) {
        // ...
    }

Algemeen

Om met wat afkortingen te beginnen:

DRY

Don't Repeat Yourself. Doe je iets herhaaldelijk, refactor dan je code en hergebruik.

KISS

Keep It Simple, Stupid. Doe niet moeilijk als het makkelijk kan. En het kan altijd makkelijk. Do The Simplest Thing That Could Possibly Work.

YAGNI

You Ain't Gonna Need It. Implementeer geen dingen die 'in de toekomst mogelijk handig zijn'. Niemand kan de toekomst voorspellen. Tegen die tijd ziet het systeem er toch al weer anders uit.

Dan nog wat overige algemene principes:

• Een klasse heeft beperkte verantwoordelijkheden: 1 taak.
• Een methode past op het scherm: een regel of 40, inclusief commentaar.
• Premature optimization is the root of all evil. Ga niet voortijdig code optimaliseren als je niet zeker weet of die code niet goed performt. Gebruik eerst een profiler.
• Als commentaar binnen een methode nodig is om de code duidelijk te maken, overweeg dan de methode op te knippen. Zet dan het commentaar boven de nieuwe methode.
• Als commentaar nodig is om de werking van de code uit te leggen, herschrijf dan de code.
• Gebruik geen taalconstructies die bijna niemand kent om te laten zien hoe goed je bent. Ga geen bits shiften om met 2 te vermenigvuldigen.
• Het gebruik van import package.* is niet toegestaan. Het doel is afhankelijkheden te beperken, en deze expliciet te benoemen. Met * introduceer je afhankelijkheden die je niet nodig hebt.
• Voorkom cyclische afhankelijkheden tussen klassen, packages en modules. Cyclische afhankelijkheden maken code breekbaar.
• Het hebben van meerdere exit points in een methode wordt aanbevolen. Het verhoogt de leesbaarheid, voornamelijk omdat je minder diep hoeft te nesten. Verlaat een methode zodra je niet verder kunt. Zie Refactoring, Improving the Design of Existing Code van Martin Fowler voor een motivatie.

  Herschrijf bijvoorbeeld:

  public String translateToDutch(String englishText) {
      if (englishText != null)
      {
          String lineToTranslate = englishText.trim();
          if (!lineToTranslate.isEmpty())
          {
              // Splits de regel in woorden in vertaal ieder woord.
              // ...
          }
      }
  }

  Naar dit:

  public String translateToDutch(String englishText) {
      if (englishText == null)
      {
          return null;
      }
      String lineToTranslate = englishText.trim();
      if (lineToTranslate.isEmpty())
      {
          return null;
      }
      // Splits de regel in woorden in vertaal ieder woord.
      // ...
  }

OOP

/**
 * Vertaalt een Engelse tekst woord voor woord naar het Nederlands.
 *
 * @param englishText De Engelse tekst die vertaald moet worden,
 *         mag niet {@code null} zijn.
 * @return De naar het Nederlands vertaalde tekst;
 *         is nooit {@code null}.
 */
public String translateToDutch(String englishText) {
    // Splits de regel in woorden in vertaal ieder woord.
    // ...
}

/**
 * Vertaalt een Engelse tekst woord voor woord naar het Nederlands.
 *
 * @param englishText De Engelse tekst die vertaald moet worden,
 *         mag niet {@code null} zijn.
 * @return De naar het Nederlands vertaalde tekst;
 *         is nooit {@code null}.
 */
public String translateToDutch(String englishText) {
    assert englishText != null;
    // Splits de regel in woorden in vertaal ieder woord.
    // ...
}

null

De meeste code is bezaaid met controles of objecten (on)gelijk aan null zijn. En toch knalt diezelfde code er (op productie) nog regelmatig uit met NullPointerExceptions. Dat geeft te denken.

Het is ook mogelijk om code te schrijven zonder de vele controles op null, zonder dat er excepties optreden.

• Schrijf contracten en hou je er aan.
• Test niet ieder object op null. Zie de contracten.
• Gebruik assert voor precondities.
• Gooi uit eigen beweging NullPointerExceptions.
• Overweeg het gebruik van het Null Object Pattern.

Logging

Excepties

Spring Container

• In de Spring Container maken we zoveel mogelijk gebruik van constructor injection. Injectie van objecten via setters doen we alleen als het niet anders kan.
• Elk component heeft een eigen Spring context. Componenten die gebruik maken van andere componenten importeren in hun context de context van die componenten.

Acegi Security

Hibernate

• Configuratie van Hibernate verloopt via annotaties in de domeinobjecten. Gevolgen:
  • Middels Configuration by Exception hoeft alleen geconfigureerd te worden wat niet standaard is. In de XML configuratie staat alles.
  • Code generatie is niet nodig. Eerst de XML configuratie schrijven en hieruit code genereren (met alle bijbehorende gevolgen) duurt naar verwachting langer dan alllen de code schrijven (er is namelijk minder code dan XML nodig).
  • De annotaties zijn niet specifiek voor Hibernate, maar generiek voor EJB3 (JPA). Dit in tegenstelling tot de XML configuratie. Het is geen doel van het project om te kunnen overgaan naar een andere ORM bibliotheek, maar onderhoudbaarheid is wel belangrijk.
• We gebruiken de Hibernate EntityManager, en voldoen daarmee aan de EJB3 specificatie. Hierdoor is de hibernate.cfg.xml configuratie niet meer nodig.
• Hibernate mag nooit de getters en setters gebruiken (ook al gebeurt dit standaard via de XML configuratie). Hibernate dient altijd rechtstreeks de private member variabelen te lezen en te schrijven. Zie ook het artikel van Martin Fowler over Anemic Domain Models.
• Alle domeinobjecten zitten in package nl.org.myapp.domain. Per component met een domeinmodel is er een aparte subpackage waarin de domeinobjecten zitten:
  • nl.org.myapp.domain.basis
  • nl.org.myapp.domain.autorisatie
  • nl.org.myapp.domain.logging
  • etc.
• Toegang naar de database verloopt via Data Access Objects (DAO's). Deze staan in package nl.org.myapp.persist. Per component is er weer een subpackage.
• Voor de DAO's gebruiken we niet de klasse HibernateDaoSupport of JpaDaoSupport> van Spring als basis. Deze klassen bieden ondersteuning voor templates (<<<HibernateTemplate>, JpaTemplate). Met Spring 2.0 zijn die niet meer nodig.

Wicket

• Alle Wicket pagina's staan in subpackages van de package nl.org.myapp.interact.webui.page
• De HTML behorende bij een pagina staat in dezelfde package als de broncode, maar niet in de src/main/java directory. In plaats daarvan staat de HTML in src/main/resources.

Quartz

Dozer

Log4J

Maven2

De volledige build van de applicatie(s) verloopt via Maven2. Daarnaast ontwikkelen we natuurlijk met een IDE. Zie voor een de configuratie van de IDE bovenop Maven2 de handleiding voor het inrichten van de ontwikkelomgeving.

Deze sectie bevat richtlijnen voor het gebruik van Maven2 zelf, los van de IDE.

• Voeg nooit zomaar een afhankelijkheid toe. Bespreek dit eerst.
• Elke module werkt met een minmale lijst van afhankelijkheden. Dus geen afhankelijk op spring, maar alleen op spring-core, spring-beans en spring-aop.

LiquiBase

LiquiBase gebruiken we om de database te onderhouden. De wijzigingen in de database staan in een verzameling XML bestanden. Op basis hiervan kan LiquiBase zelf de database bijwerken. Het is daarmee niet nodig dat ontwikkelaars elkaar er op wijzen dat er een databasewijziging is geweest; de wijzigingen worden automatisch verwerkt.

Interactielaag

Proceslaag

Persistentielaag