Een manifest voor ontwikkelaars

Ik ga graag op bezoek bij collega’s en concullega’s. Naast dat het goed is voor mijn netwerk, is het gewoon een hele mooie gelegenheid om van elkaar te leren.

Een van de punten waar ik vaak een suggestie toe doe is het maken van een ‘ontwikkelaars manifest’. Niets bijzonders, in de basis gewoon een documentje met een aantal afspraken en richtlijnen voor het ontwikkelteam, maar wat mij betreft een documentje met enorm veel voordelen.

Om te beginnen dwingt het schrijven van een manifest tot reflectie. Hoe wordt er ontwikkeld? Wat wordt er gedaan met tussenresultaten? Waar laten we de programmatuur? Hoe wordt er getest? Hoe wordt er opgeleverd?

Het schrijven zorgt vaak voor een herziening van de (vaak tot dan impliciete) procedures voor ontwikkeling en release. Vaak met snellere/meer foutloze opleveringen als gevolg.

Een ander voordeel is dat het manifest zorgt dat alle ontwikkelaars op dezelfde lijn komen. Door het manifest wordt duidelijk wat men van elkaar kan verwachten en wordt de code geschreven  o.b.v. een gedeelde standaard, waardoor ontwikkelaars flexibeler zullen worden in het aanpassen en beoordelen van elkaars werk. (feitje: een regel code wordt 8 keer vaker gelezen dan geschreven.).


Zelf ééntje schrijven? Neem ter inspiratie onderstaande kopie van het concept manifest voor mijn huidige opdracht. Merk op dat de afspraken redelijk abstract zijn. De concrete procedures worden door het team zelf geschreven in aparte handleidingen.

Maatwerk manifest.

  1. Met maatwerk veranderen we geen standaard programmatuur.
    Uitzonderingen worden in het team besproken.
  1. Het doel, alle ontwerpbeslissingen en de plaats binnen de architectuur van het maatwerk wordt gedocumenteerd..
  2. Al het maatwerk wordt vergezeld door unit-tests.
  3. Al het maatwerk wordt vastgelegd in subversion.
    Vermeld story of issue-nr bij checkin.
  1. Het maatwerk (de programmatuur) is zelf beschrijvend of wordt vergezeld met verklarend commentaar/(java)doc
  2. Maatwerk wordt opgeleverd met buildscript/instructie t.b.v. Jenkins-CI.
    t.b.v. uitvoeren tests, compileren en deployen.

 

Richtlijnen:

Aan alle teamleden de aanbeveling om ten minsten notie te nemen van de volgende aanbevelingen, en waar relevant toe te passen binnen het eigen werk. Onderstaande betreft een verzameling van tips & regels uit eigen ervaring of literatuur.

Software design

Best practices

  1. Weest bewust van veel voorkomende design patterns. Je collega’s gebruiken ze.
  2. ‘Designing for test’ zorgt voor een beter ontwerp door vermindering in afhankelijkheden, formelere interfaces en betere abstractie & modularisatie.
  3. Identificeer de elementen die mogelijk onderhevig zullen zijn aan verandering. Scheid en isoleer deze.
  4. ‘Schets’ je functies/klassen/packages eerst uit op papier. Dit scherpt je concepten, toetst je aanpak en maakt het beheersbaarder.
  5. Pas ‘information hiding’ toe. (Wat moet de buitenwereld weten?)
  6. Streef naar loose coupling.
    1. Zoveel mogelijk onafhankelijk van andere modules.
    2. Duidelijke lijntjes/relaties.

Code-kwaliteit

Naamgeving

  1. De naam beschrijft zo volledig mogelijk het doel.
  2. Geen cryptische ambigue termen.
  3. Liever lang en duidelijk, dan kort en verwarrend.
  4. Namen als i en j zijn geaccepteerd voor simpele loops.
    1. Gebruik een betekenisvolle naam bij lange loops, lange blocks of geneste loops.
    2. Gebruik ook for—each.
  5. Houdt status-variabelen specifiek. B.v. dataReady, needsRecalc, containsErrors. Ipv flag, status, error.
  6. Ook tijdelijke variabelen hebben een naam.
  7. Booleanse variabelen hebben een naam die impliceert dat hij waar/niet waar is.
  8. Zorg dat de members van ENUMS herkenbaar zijn. B.v. door prefixing.
    enum color {color_red, color_blue)
  9. Java: Baseer je code-style op de java/eclipse conventies. Conformeer je stijl waar nodig.
    1. Probeer bij het aanpassen van code – in een ander zijn stijl- zijn stijl ‘licht’ te adopteren als dit de leesbaarheid vergroot.
    2. I en j zijn indexes.
  10. Constanten zijn in CAPS.
  11. Class/Interface: Alle woorden beginnen met een hoofdletter.
  12. Variabelen: beginnen met een kleine letter, daarna alle woorden met een hoofdletter.
  13. Underscore ‘_’ wordt niet gebruikt behalve in CAPS.
  14. Afkortingen: prima, als ze maar bekend zijn.
  15. Javascript: Schrijven met als doel de filesize klein te houden bestaat niet. Gebruik een buildscript om je jeavascript te compileren, zoals de YUI compressor

Variabelen

  1. 1 variabele heeft 1 doel/functie. En nooit een tweede (verborgen) functie.
  2. Controlleer of input variabelen valide zijn (precondition checks)
  3. Beperk de ‘distance of declaration’. De ruimte tussen assignment en 1e
  4. Declareer (of her initialiseer) een variabele bij voorkeur net voor gebruik.
  5. Groepeer gerelateerde statements. Splits ze eventueel op in aparte functies of scope-blocks.
  6. Begin altijd met de meest beperkte scope (geldt uiteraard ook voor functies en classes).
  7. Wees bekend met de termen/concepten: coding time, compile time, load time, object instantiation time en just im time.
  8. Latere binding-time van variabelen verhoogt flexibiliteit.
  9. Voorkom in ieder geval magic numbers (coding time).

Classes & packages

  1. Betekenisvol, de naam beschrijft het doel.
  2. Voorkom imperatieve afhankelijkheden in aanroep tussen publieke functies.

 

Maatwerk IBM Content Navigator

  1. Javascript: Er wordt geen gebruik gemaakt van extra plugins zoals JQuery. Uitgangspunt is Dojo.
  2. Gebruik altijd asynchrone communicatie. Ken het scoping concept van closures.
  3. Bij plugins buiten het standaard plugin model
    1. Houdt extra rekening met naamgeving / beschrijving.
    2. Documenteer!
  4. Verkies ICN services boven webservices.
    1. Juist i.v.m. security.
    2. Plaats ‘generieke services in een generieke service plugin.
    3. Service exposen naar Workflows? Dan wel via webservices, maar met re-use (import) van de service.
  5. Voor extensies buiten het plugin model:
    1. Houdt rekening met conflicten door andere plugins (b.v. Enterprise Records).
    2. Weet wanneer je moet/kan kiezen voor een object-override of klasse override.
    3. Gebruik dojo mixin,extend, ..
    4. Je opties zijn: override, monkey patch prototype
  6. Zorg voor een passende betekenisvolle naam/omschrijving.

 

One thought on “Een manifest voor ontwikkelaars

Leave a Reply to Ivo Jonker Cancel reply

Your email address will not be published. Required fields are marked *