about software programming techniques

JJ van Zon 2023

[ Draft ]

➕ Appendices

back

Contents

Appendix A: Layering Checklist

This checklist might be used if you want to bulk-program the architecture for an application by going through all the layers one by one, or if you want to build a feature and make sure you have not forgotten any technical issues.

Appendix B: Knopteksten en berichtteksten in applicaties (resource strings) [ Dutch ]

< TODO: Translate to English. >

Er is een structuur waarmee we knopteksten en meldingen in onze applicaties kunnen organiseren. Het doel is om deze teksten maximaal herbruikbaar te maken, vertaalwerk te minimaliseren en correcte teksten te gebruiken. Hiervoor plaatsen we algemene teksten op een bepaalde locatie, domein termen op een andere en specifieke projecten krijgen de overige teksten. Dit kan het aantal teksten drastisch verminderen van 10.000 tot misschien een paar 100.

Momenteel worden resources op allerlei plekken geplaatst met willekeurig hoofdlettergebruik en gebruik van leestekens. En in andere gevallen werden ze helemaal niet gebruikt en stond alles hard op één taal.

Om dit beter aan te pakken, zouden we graag willen dat ontwikkelaars zowel Nederlandse als Engelse teksten toevoegen aan de resource files. Als er twijfel is over het Engels, kun je het misschien een collega vragen.

Hoofdletters, interpunctie, spelling

Hoofdlettergebruik etc. is conform de taalregels van de betreffende taal.

  1. Resources kunnen hele zinnen zijn. Die moeten correct geschreven zijn: In het Nederlands begint dat met een hoofdletter en eindigt het met een punt, tenzij het een vraag is, dan met een vraagteken.
  2. Voor Engels gebruiken we de Amerikaanse spelling.
  3. Namen van properties, classes en andere titels zoals knopteksten zijn in het Nederlandse zijn als volgt: “Links in artikel”, dus alleen beginnen met een hoofdletter. En dus geen punt erachter.
  4. Namen van properties, classes en andere titels zoals knopteksten in Engelse titels doen we als volgt: “Table of Contents”, dus alle woorden beginnen met een hoofdletter, alleen onbelangrijke woorden zoals “in”, “and”, etc. in kleine letters.
  5. Er is dus een verschil in hoofdlettergebruik tussen volzinnen en losse titels.

Assemblies

Resources worden met de assemblies meegecompileerd*.

Termen worden zo veel mogelijk hergebruikt. Daarom zijn er plekken bedacht waar de termen thuis horen. Je kunt in deze volgorde op zoek naar een resource die misschien al bestaat:

  1. “Save”, “Close”, “Edit”, etc. staan in JJ.Framework.Resources, toegankelijk via de CommonResourceFormatter class.
  2. Validatiemeldingen uit JJ.Framework.Validation, toegankelijk via de ValidationResourceFormatter class.
  3. CanonicalModel: een tussenmodel voor uitwisseling van gegevens tussen verschillende systemen, toegankelijk via de CanonicalResourceFormatter class.
  4. Business layers bevatten alleen vertalingen voor de overige teksten die niet in het canonical model staan.
  5. Ook teksten die niet direct domeintermen zijn, maar wel in applicaties worden gebruikt op plekken waar het gaat over een bepaald functioneel domein, mogen in de business layer worden gezet.
  6. Presentation layer bevat over het algemeen geen teksten. Die zetten we in de business layer, om niet te veel plekken te hebben met resources.

Tips

  1. Gebruik van placeholders zoals {0} is ok, maar dan liefst wel met een class erbij, die de placeholders vervangt (een ResourceFormatter). Zie JJ.Framework.Resources voor een voorbeeld. Je kunt dan het beste de resources zelf internal te maken en alleen de class die de placeholders vervangt public maken. Hou het geschikt voor meerdere talen, want een creatief met placeholder opgebouwde resource string werkt al gauw niet voor een andere taal.
  2. Maak je niet druk om dat het kan resulteren in teksten met hoofdlettergebruik zoals: “Het Ordernummer is niet ingevuld bij de Bestelling.” Zouden we dit aanpakken, dan doen we dit misschien liever dynamisch via een algoritme om het hoofdlettergebruik kloppend te maken.
  3. Het is misschien verstandig om teksten in de applicatie algemeen te houden. Dus bijv. “Artikelen”, i.p.v. “Artikelen in dit boek”. Dit scheelt vertaalwerk. Ook deze ‘dubbele punt’ notatie is verstandig: “Artikel 1: Naam is verplicht.” Daarbij zijn de teksten “Artikel”, “Naam” en “{0} is verplicht.” waarschijnlijk al vertaald en hoeft dat niet nog eens opnieuw. Deze ‘dubbele punt’ notatie (“Artikel 1:”), kan zorgen dat het ook blijft werken voor talen met een andere zinsbouw.

* Resources staan liever niet in een database, omdat het applicaties trager kan maken en kun je de code niet draaien op omgevingen waarbij je geen toegang hebt tot de database. In sommige situaties kun je dan niet compileren zonder toegang te hebben tot een specifieke database. Bovendien geeft mee compileren van resources in specifieke projecten ons de mogelijkheid dubbelzinnige termen anders te vertalen per business domein.

back