Utviklingsretningslinjer

Innholdsfortegnelse

1. Hvordan koden din bør se ut
2. Hvordan formateringen din bør se ut
3. Hvordan javadoc-en din bør se ut
4. Internasjonalisering

Hvordan koden din bør se ut

• sørg for at koden er kompatibel med Java 11
• Dokumenter koden din ved hjelp av inline-kommentarer og javadoc. Mange vil takke deg :)
• Prøv å unngå offentlige felt
• JOSM har mange hjelpemetoder i klassene Utils, GuiUtils, Geometry ... Bruk dem hvis du trenger det
• Sjekk parametere. Du kan bruke Objects.requireNonNull.
• Ikke skriv for ytelse - skriv for lesbarhet. Bruk Streams, Functions og andre Java 8+ funksjoner hvis de gjør koden mer lesbar.

Tråding / Låsing

• JOSM bruker ulike låsemekanismer, avhengig av objektet.
• Datasett er beskyttet av en RW-lås. Noen metoder låser ikke automatisk av ytelsesgrunner. Sørg for å skaffe de nødvendige låsene for endringene dine.
• GUI-komponenter skal bare endres i EDT-tråden
• Foretrekk å bruke SwingUtils.invokeLater hvis du trenger å kjøre noe på UI-tråden
• Mange lyttere kjører allerede i EDT-tråden (lagendringer) eller har en sentral manager som lar deg registrere lyttere som kjører i EDT (dataendringer, valgendringer).

Hvordan formateringen din bør se ut

• sørg for at det ikke er etterfølgende mellomrom
• ikke bruk flere påfølgende tomme linjer
• JOSM bruker 4 tegn innrykk og ingen tabulatorstopp. Hvis du bruker Notepad++, kan du endre standardinnrykket i "Innstillinger" -> "Språk" -> "Tabulatorinnstillinger" -> merk av for "Erstatt med mellomrom" (dette er permanent) eller med knappen "endre innrykksinnstillinger" i verktøylinjen (dette er en midlertidig innstilling og krever tillegget "Tilpass verktøylinje").
• legg til krøllparenteser for hver if, med mindre den følges av return (eller kanskje throw)
• Du bør bruke checkstyle før patch/commit: ant checkstyle og sjekk checkstyle-josm.xml; hvis du synes det er tregt å kjøre checkstyle for alle filer, kjør bare for endrede filer:

    # sørg for at build2-katalogen eksisterer, hvis den ikke gjør det, kjør 'ant checkstyle-compile' først
  
    svn diff --summarize | awk '{ print $2 }' | grep "^[a-z]" | xargs \
      java -classpath "build2:tools/checkstyle/checkstyle-all.jar" \
        com.puppycrawl.tools.checkstyle.Main -c tools/checkstyle/josm_checks.xml
    # eller
    git diff --name-only | xargs \
      java -classpath "build2:tools/checkstyle/checkstyle-all.jar" \
        com.puppycrawl.tools.checkstyle.Main -c tools/checkstyle/josm_checks.xml
  

Hvordan javadoc-en din bør se ut

• ​Oracle Javadoc-stilguide brukes som basisguide
• @since brukes for offentlige klasser og metoder (synlige for plugin-utviklere) med JOSM-revisjonen som introduserte elementet. Eksempel: @since 5408
  • @since oppdateres/legges til når en offentlig metode signatur endres eller hvis en klasse endres navn.
  • @since kan utelates for offentlige metoder og felt introdusert samtidig med klassen, forutsatt at de ikke har endret seg og klassen er riktig dokumentert.
  • Det kan være flere @since-merker, f.eks. for å legge til grensesnitt til en klasse. Grunnen til disse merkene bør legges til. Eksempel: @since 12345 @FunctionalIterface ble lagt til
  • Hvis du sender inn en patch og ikke kjenner revisjonen, legg til @since xxx uansett. Den kan erstattes når patchen din flettes.
• @throws foretrekkes fremfor @exception
• sjekk endringene dine før patch/commit ved å generere javadoc: ant javadoc, bla gjennom utdatameldinger; hvis du synes det er tregt å kjøre javadoc for alle filer, kjør bare for endrede filer:

    svn diff --summarize | awk '{ print $2 }' | xargs javadoc -d javadoc
    # eller
    git diff --name-only | xargs javadoc -d javadoc

Konfigurering av Eclipse

Internasjonalisering

• sørg for at du bruker tr(...) for alle lokaliserte strenger

  import import static org.openstreetmap.josm.tools.I18n.tr;
  
  // bruk tr(...) for unntaksmeldinger
  //
  throw new Exception(tr("feilmelding alltid i tr()"));
  
  // bruk tr(...) for etiketter, titler, verktøytips og lignende
  //
  new JLabel(tr("Etikette alltid i tr()"));
  
  // osv.
  

• sammensett aldri lokaliserte meldinger med +. Bruk formatplassholdere i stedet.

IKKE GJØR new JLabel(tr("Min etikett " + labelId));

GJØR new JLabel(tr("Min etikett {0}",labelId));

Unntak: + kan brukes til å bryte lange linjer med ikke-variable tekster. Plassholderne er obligatoriske i enkle oversettelser.

• Når du bruker apostrof i kildestrengen, må den escapes med en annen apostrof (som backslash i C):
  

  new JButton(tr("Ikke trykk på meg!"))
  

• En oversettelseskontekst kan settes med trc(...). Ytterligere hint til oversettere gis av java-kommentarer ved funksjonen:

  /* I18n: husnummer, gate som parameter; plasser nummer først for synlighet */
  msg = tr("Husnummer {0} ved {1}", s, t);
  

• Bruk trn(...) for å la oversettere velge det språkspesifikke flertallet:

  msg = trn("Objekt slettet", "Objekter slettet", del.size();
  
  // eller med plassholdere:
  //
  new JButton(trn(/* I18n: nødvendige ganger, noe navn som parameter */ 
                      "Trykk {1} {0} ganger!", n, n, someName))
  
  // Den engelske entallsstrengen må oppgis for identifikasjon 
  // selv når den er logisk ugyldig og ikke vil forekomme. For konsistens 
  // bør nummerplassholderen settes i den.
  //
  msg = trn("Kombiner {0} vei", "Kombiner {0} veier", n, n);
  

I flertallssegmenter er ingen plassholder obligatorisk for oversettere.

---

Tilbake til Utviklerveiledning (en)