Richtlijnen voor ontwikkelen

Inhoud

1. Hoe uw code er uit zou moeten zien
2. Hoe uw opmaak eruit zou moeten zien
3. Hoe uw javadoc er uit zou moeten zien
4. Internationalisatie

Hoe uw code er uit zou moeten zien

• zorg er voor dat de code compatibel is met Java 8
• Documenteer uw code met behulp van commentaar op de regel en javadoc. Vele mensen zullen u daarvoor danken :)
• Probeer publieke velden te vermijden
• JOSM heeft heel veel hulpmethoden in de klassen Utils, GuiUtils, Geometry .... Gebruik ze als u ze nodig hebt.
• Controleer parameters. U kunt Objects.requireNonNull gebruiken.
• Schrijf niet voor de uitvoering - schrijf voor leesbaarheid. Gebruik Streams, Functions en andere objecten van Java 8 als dat de code beter leesbaar maakt.

Threading / Vergrendeling

• JOSM gebruikt verschillende mechanismen om te vergendelen, afhankelijk van het object.
• De gegevenssets worden beschermd door een RW-vergendeling. Sommige methoden vergrendelen niet automatisch om redenen van uitvoering. Zorg er voor de vergrendelingen aan te roepen die voor uw wijzigingen nodig zijn.
• Componenten van de GUI zouden alleen moeten worden aangepast in de EDT-thread
• Gebruik bij voorkeur SwingUtils.invokeLater indien u iets moet uitvoeren in de UI-thread
• Veel listeners worden al uitgevoerd in de EDT-thread (laagwijzigingen) of hebben een centrale beheerder die u toestaat listeners te registreren die worden uitgevoerd in de EDT (wijzigingen in gegevensset, wijzigingen in selectie).

Hoe uw opmaak eruit zou moeten zien

• zorg er voor dat er geen witruimte achter staat
• gebruik niet meerdere lege regels achter elkaar
• JOSM gebruikt 4 tekens voor inspringen en geen tabstops (Als u Notepad++ gebruikt kunt u de standaard inspringing wijzigen in de "Instellingen" -> "Voorkeuren" -> "Language" -> "Tab settings" -> selecteer "Omzetten in spaties" (dit is permanent) of met de knop "Instellingen insprong wijzigen" in de werkbalk door het vinkje te verwijderen bij "Tabs gebruiken" (dit is een tijdelijke instelling).)
• voeg gekrulde haken toe voor elke if, tenzij die wordt gevolgd door een return (of misschien een throw)
• U zou checkstyle moeten gebruiken vóór patch/commit: ant checkstyle en controleer checkstyle-josm.xml; indien u vindt dat het uitvoeren van checkstyle te lang duurt voor alle bestanden, voer het dan alleen uit op de gewijzigde bestanden:

  # make sure build2 dir exists, if it does not run 'ant checkstyle-compile' before

  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
  # or
  git diff --name-only | xargs \
    java -classpath "build2:tools/checkstyle/checkstyle-all.jar" \
     com.puppycrawl.tools.checkstyle.Main -c tools/checkstyle/josm_checks.xml

Hoe uw javadoc er uit zou moeten zien

• De ​Oracle Javadoc style guide wordt gebruikt als gids voor de basis
• @since wordt gebruikt voor publieke klassen en methoden (zichtbaar voor de ontwikkelaars van invoegtoepassingen) met de revisie van JOSM waarin het element werd geïntroduceerd. Voorbeeld: @since 5408
  • @since wordt bijgewerkt / toegevoegd als een handtekening van een publieke methode wijzigt of indien een klasse een andere naam krijgt
  • @since kan worden weggelaten voor publieke methoden en velden die tegelijkertijd met de klasse worden geïntroduceerd, vooropgesteld dat zij niet zijn gewijzigd en de klasse juist is gedocumenteerd.
  • Er kunnen meerdere tags @since zijn, bijv. voor het toevoegen van interfaces aan een klasse. De reden voor deze tags zou moeten worden toegevoegd. Voorbeeld: @since 12345 @FunctionalIterface werd toegevoegd
  • Indien u een patch indient en u weet de revisie niet, voeg dan toch @since xxx toe. Het kan dan worden vervangen bij het samenvoegen van uw patch.
• @throws heeft de voorkeur boven @exception

• controleer uw wijzigingen vóór patch/commit door het genereren van javadoc: ant javadoc, blader door de uitvoerberichten; indien u vindt dat het uitvoeren van javadoc te lang duurt voor alle bestanden, voer het dan alleen uit op de gewijzigde bestanden:

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

Eclipse configureren

Internationalisatie

• zorg er voor dat tr(...) gebruikt voor alle gelokaliseerde tekenreeksen

  import import static org.openstreetmap.josm.tools.I18n.tr;
  
  // gebruik tr(...) voor berichten van uitzonderingen
  //
  throw new Exception(tr("foutenbericht altijd in tr()"));
  
  // gebruik tr(...) voor labels, titel, teksten van helptips en soortgelijke 
  //
  new JLabel(tr("Label altijd in tr()"));
  
  // etc.
  

• assembleer gelokaliseerde berichten NOOIT met +. Gebruik in plaats daarvan tijdelijke plaatsaanduidingen voor opmaak.

NIET new JLabel(tr("Mijn label " + labelId));

MAAR new JLabel(tr("Mijn label {0}",labelId));

Enige uitzondering: + kan worden gebruikt om lange regels van niet-variabele teksten af te breken. De plaatsvervangers zijn verplicht in eenvoudige vertalingen.

• Bij het gebruiken van een apostrof in de tekenreeks voor de bron, moet die zijn geëscaped door een andere apostrof (Zoals de backslash in C):
  

  new JButton(tr("Don''t press me more than {0} times!", n))
  

• Een context voor een vertaling kan direct worden ingesteld met trc(...). Aanvullende hints voor vertalers worden gegeven in opmerkingen voor Java bij de functie:

  /* I18n: huisnummer, straat als parameter; plaats nummer eerst voor zichtbaarheid */
  msg = tr("House number {0} at {1}", s, t);
  

• Gebruik trn(...) om vertalers de taalspecifieke meervoudsvorm te laten kiezen:

  msg = trn("Object deleted", "Objects deleted", del.size();
  
  // of met plaatsvervangers:
  //
  new JButton(trn(/* I18n: keer nodig, een naam als parameter */
                      "Press {1} {0} times!", n, n, someName))
  
  // De Engelse enkelvoud tekenreeks voor de bron moet worden opgegeven voor identificatie
  // zelfs als dat logisch gezien ongeldig is en niet zal voorkomen. Voor consistentie
  // zou de plaatsvervanger voor het nummer erin moeten zijn ingesteld.
  //
  msg = trn("Combine {0} way", "Combine {0} ways", n, n);
  

  In segmenten voor meervoud is een plaatsvervanger niet verplicht voor vertalers.

---

Terug naar Developers Guide (en)