wiki:Nl:DevelopersGuide/StyleGuide

Version 13 (modified by DiGro, 4 months ago) (diff)

adjusted to revision 34

Andere talen:

Richtlijnen voor ontwikkelen

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.

  • Bij het gebruiken van een apostrof, zijn de volgende regels van toepassing:

Voor alle tr is de apostrof speciaal. (Zoals de backslash in C)
Hij moet worden geëscaped door een andere apostrof:

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


Terug naar Developers Guide?