Denne side beskriver de anvendte principper for brugen af danske sprog i STARs udstilling af webservices. Ydermere forholder siden sig til, hvor og hvornår udviklere kodemæssigt kan benytte sig af det engelske sprog og engelske termer.

1 Grundprincipper
2 Eksempler
- 2.1 Servicelag
- 2.2 Forretningslogik (forretningslaget)
- 2.3 Domæne objekter
- 2.4 Data Access
- 2.5 Udstillede events
- 2.6 Database

Grundprincipper

Følgende grundprincipper anvendes:

Servicesnitflader til REST services kodes på dansk i alle forretningsdomæner (siloer). Dette for at understøtte STARs princip om dansk navngivning i servicesnitflader. Dette princip er ensbetydende med, at alle servicesnitfalder i form af Swagger-kontrakter og indholdet i Swagger-kontrakter udstilles på dansk. Derfor skal nedenstående elementer til servicesnitflader kodes på dansk:
- navne på metoder, dog tillades brugen af Get, Post og Put, som en del af metodenavnet, når metodenavnet ikke indgår i servicesnitflader.
- navne på parametre, som indgår i servicesnitfalder.
- Data Transfer Objects (DTO’er) til Requests og Responses i servicesnitflader.
- indhold i HTTP templates.
- navne såvel som Enum værdier til kodelister.
- fejlkodetekster.
Forretningslogik (forretningslaget), der ligger under servicesnitflader kodes på engelsk. Dette er gældende for:
- CQS Features med deres tilhørende Requests og Responses.
- Andet forretningslogik i form af valideringsmetoder, hjælpeklasser m.m.
Domæne objekter kodes på engelsk dog med undtagelse af kodelister, hvor navne såvel som Enum værdier kodes på dansk, da de vil indgå i servicesnitflader.
Data Access i form af Storage klasser, Stored Procedures, navne på tabeller samt navne på felter kodes på engelsk. Dog angives tabel- og feltbeskrivelser på dansk af hensyn til SUP samt aflevering til Statens Arkiver.
Navne samt Properties på Events, der publiceres til og aftages fra Event Brokeren, kodes på dansk
Sikkerhedsheaders samt lignende standardelementer, såsom WSRM base-modellem kodes på engelsk.
I både SOAP og REST servicesnitflader erstattes æ, ø og å med respektive ae, oe og aa for en sikkerheds skyld indtil andet er aftalt med aftagere.
Der anvendes ikke æ, ø eller å i kompileret kode.

Oversættelse af forretningsbegreber i servicesnitfladen fra dansk til engelsk er FA’erne ansvarlige for i samarbejde med de enkelte udviklingsteams.

Navngivning af events, der publiceres og aftages fra Event Brokeren

Events navngives efter mønsteret: Star.<Forretningsdomæne/silo>.Events.<Forretningsområde>.<Version>.<Eventnavn>. F.eks. Star.VisiteringOgStatus.Events.Kontaktgrupper.V1.KontaktgruppeOpdateretEvent, som forretningsdomænet Visitation og status publicerer ved oprettelse af kontaktgrupper, ved kontaktgruppeskift samt ved lukning af kontaktgrupper.

Event NuGet pakker: Star.<Forretningsdomæne/silo>.Events. F.eks. Star.VisiteringOgStatus.Events, når forretningsdomænet Visitering og status udstiller en NuGet pakke indeholdende alle de events, som forretningsdomænet publicerer.

Event receiver: Star.<Modtagne forretningsdomæne/silo>.<Afsendende forretningsdomæne/silo>.EventReceiver. F.eks. Star.Jobsearch.VisiteringOgStatus.EventReceiver, når forretningsdomæne JobSearch skal modtage events fra forretningsdomænet Visitering og status.

Se flere eksempler og kontekst på https://starwiki.atlassian.net/wiki/spaces/CITY/pages/2522874147

Kodelister

Oversættes til dansk. En liste med oversættelser af DFDG Classic kodelister findes her: https://starwiki.atlassian.net/wiki/spaces/UDV/pages/22577260

Fejlkoder

Oversættes til dansk. En liste med kendte oversættelser findes her: https://starwiki.atlassian.net/wiki/spaces/UDV/pages/3911549117

Navngivningsprincipper

Der anvendes sammenbindings-s. Eksempelvis: GetUddannelseshjaelp

Der anvendes camelCase (som hidtil) men kun hvor mellemrum bortfalder (dvs. der anvendes normal dansk sammensætning af ord - og med visse, vedtagne undtagelser, nævnt nedenfor).

Ved skift imellem forretningstermer og tekniske termer, og dermed imellem respektive dansk og engelsk markeres dette også med stort bogstav. Fx U med stort, H med småt og intet s foran den tekniske term Service i PensionService.GetUddannelseshjaelp.

Elementer som defineres ved en kodeliste får “Type“ påsat medmindre det er åbenbart hvilken informationsvariant der er tale om. Eksempler: FriststatusType, FristType, Kontaktgruppe og Personkategori.

Som udgangspunkt gælder navngivningsreglerne forretningselementer, idet vi skelner mellem Type (1) og Element (2) (de røde tal i grafikken nedenfor), men somme tider hænger de sammen.

I Type skal vi selvfølgelig have dto'er, og det er i øvrigt generelt udviklerne der har hånd- og halsret over Type-laget.

Element har FA og PO til gengæld hånd- og halsret over, og der har vi sommetider brug for Struktur, som fx ved (3). Når vi har brug for den, sætter vi den på, men kun når det er påkrævet for klart at indikere at der er tale om et strukturerende element (i modsætning til et single-value).

Samling er erstatningen for Collection (som har været rigtigt meget brugt i DFDG), men kan ofte erstattes af flertal, fx kan man let bruge Persongruppemarkeringer isf. Persongruppesamling.

Vi tilstræber flertalsformen, men af og til bruger samling når vi mener at det er den bedste forretningsmæssige ordform (hele målet med dansk er jo at forretningen skal kunne forstå og genkende sine forretningstermer i vores services).

Eksempel på begge:

Element	Forekomst

Element	Forekomst
Møde	1
- Mødested	1
- MødeStarttidspunkt	1
- MødeSluttidspunkt	1
- Mødedeltagere	1
- - Mødedeltager	0 - *
- - - Navn	1
- - - Rolle	1

Elementer til angivelse af dato og tid postfixes med henholdsvis ‘dato' og 'tidspunkt’.

Nogle specifikke termer:

Id bruges når der er tale om et unikt id, hvor vi på engelsk ville bruge identifier.

Eksempler

Servicelag

REST services implementeres på dansk, så Swagger-kontrakter udstilles på dansk. Dette er illustreret i nedenstående tænkte eksempel:

https://kontaktforloeb.bm.dk/v1/afholdtsamtale?fraDato=2019-01-01&tilDato=2019-12-31

Den tilsvarende controller vil hedde AfholdtSamtaleController og metoden GetAfholdteSamtalerIPeriode som vist nedenfor:

/// <summary>
/// Henter alle afholdte samtaler i en given periode.
/// </summary>
[AllowAccess(OrganisationTypeCodeList.AKasse, AccessToEnum.OwnPersons)]
[AllowAccess(OrganisationTypeCodeList.JobCenter, AccessToEnum.OwnPersons)]
[AllowAccess(OrganisationTypeCodeList.Kommune, AccessToEnum.OwnPersons)]
[AllowAccess(OrganisationTypeCodeList.STAR, AccessToEnum.AllPersons)]
[ErrorCodes(ExceptionManager.Code.PersonDoesNotExist, ExceptionManager.Code.BorgerIkkeMedlemAfAKasse, ExceptionManager.Code.DetAngivneAfholdtSamtaleIdentifierErIkkeKendtISystemet)]
public Task<AfholdtSamtaleResponseDto> GetAfholdtSamtale([FromQuery][Required] DateTime fraDato, [FromQuery][Required] DateTime tilDato, [FromHeader][CivilRegistrationIdentifier] string civilRegistrationIdentifier)
{
    ...
}

Forretningslogik (forretningslaget)

Forretningslogik implementeres på engelsk gældende for både CQS Features, herunder Command Features, Query Features, Event Handler Features og Batch Job Features. Ligeledes implementeres validerings- såvel som hjælpeklasser på engelsk. Dette illustreret i nedenstående tænkte eksempler:

public class GetInterviewsInPeriodRequest : IRequest
{
    public string CivilRegistrationIdentifier { get; }
    public DateTime FromDate { get; }
    public DateTime ToDate { get; }
    public ISecurityContext SecurityContext { get; }

    public GetInterviewsInPeriodRequest(string civilRegistrationIdentifier, DateTime fromDate, DateTime toDate, ISecurityContext securityContext)
    {
        CivilRegistrationIdentifier = civilRegistrationIdentifier;
        FromDate = fromDate;
        ToDate = toDate;
        SecurityContext = securityContext;
    }
}

Nedenstående viser eksempler på klassenavne i forretningslaget:

InterviewValidator
InterviewHelper
CommonValidator
PersonCategoryResolver

Domæne objekter

Domæneobjekter implementeres på engelsk og Postfixes med Model, som illustreret i nedenstående tænkte eksempel:

Kodelister implementeres på dansk og Postfixed med CodeList, som illustreret i nedenstående tænkte eksempel:

Data Access

Eksempler på klassenavne:

InterviewStorage

Udstillede events

Events som udstilles med danske navne. Se eksempler . Dette gælder også fra DFDG.

Database

Fremadrettet implementeres nye tabeller, nye felter samt nye Stored Procedures på engelsk. Der gøres p.t. ikke noget ved de eksisterende tabeller, felter samt Stored Procedures, hvilket p.t. kan betyde, at en tabel sagtens kan indeholde en blanding af danske og engelske kolonner som vist i dette tænkte eksempel:

Engelsksprogede felter (kolonner) til angivelse af dato og tid Postfixes med henholdsvis Date og DateTime.

Dansksprogede felter (kolonner( til angivelse af dato og tid Postfixes med henholdsvis Dato og Tidspunkt henholdsvis.

Fysisk arkitektur

Den gode brug af det danske og engelske sprog i DFDG Classic og forretningsdomæner (siloer)