Lignes directrices pour le développement

Table des matières

1. À quoi devrait ressembler votre code
2. Comment devrait se présenter votre mise en forme
3. À quoi devrait ressembler votre javadoc
4. Internationalisation
5. Voir également

À quoi devrait ressembler votre code

• Assurez-vous que le code est compatible avec Java 11.
• Documentez votre code en utilisant les commentaires en ligne et javadoc. De nombreuses personnes vous en remercieront :) :)
• Essayez d’éviter les champs publics.
• JOSM a beaucoup de méthodes d’aide dans les classes Utils, GuiUtils, Geometry ... utilisez-les si vous en avez besoin.
• Vérifiez les paramètres. Vous pouvez utiliser Objects.requireNonNull.
• N’écrivez pas pour la performance – écrivez pour la lisibilité. Utilisez Streams, Functions et d'autres fonctionnalités de Java 8+ si elles rendent le code plus lisible.

Threading / Verrouillage

• JOSM utilise différents mécanismes de verrouillage, en fonction de l'objet.
• Les ensembles de données sont protégés par un verrou RW. Certaines méthodes ne sont pas verrouillées automatiquement pour des raisons de performance. Assurez-vous de développer les verrous nécessaires à vos modifications.
• Les composants de l'interface graphique ne doivent être modifiés que dans le fil (thread) EDT.
• Préférez utiliser SwingUtils.invokeLater si vous avez besoin de lancer quelque chose sur le thread de l'interface utilisateur.
• De nombreux listeners s'exécutent déjà dans le thread EDT (changements de couches) ou disposent d'un gestionnaire central qui vous permet d'enregistrer des listeners qui s'exécutent dans EDT (changements de jeux de données, changements de sélection).

Comment devrait se présenter votre mise en forme

• Assurez-vous qu'il n'y a pas d'espace blanc à la fin.
• N'utilisez pas plusieurs lignes vides consécutives.
• JOSM utilise une indentation de 4 caractères et aucun arrêt de tabulation. Si vous utilisez Notepad++, vous pouvez changer l'indentation par défaut dans les “Préférences” -> “Langue” -> “Paramètres de tabulation” -> cocher “Remplacer par des espaces” (ceci est permanent) ou avec le bouton “changer les paramètres d'indentation” dans la barre d'outils (ceci est un paramètre temporaire et nécessite le greffon "Customize Toolbar").
• ajouter des crochets pour chaque if, sauf s'il est suivi de return (ou peut-être throw).
• Vous devriez utiliser checkstyle avant le patch/commit : ant checkstyle et vérifiez checkstyle-josm.xml; si vous trouvez que l'exécution de checkstyle est lente pour tous les fichiers, exécutez-la uniquement pour les fichiers modifiés :

    # vérifiez que le répertoire build2 existe, si ce n'est pas le cas lancez 'ant checkstyle-compile' avant
  
    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
    # ou
    git diff --name-only | xargs \
      java -classpath "build2:tools/checkstyle/checkstyle-all.jar" \
        com.puppycrawl.tools.checkstyle.Main -c tools/checkstyle/josm_checks.xml
  

À quoi devrait ressembler votre javadoc

• Le ​guide de style de Javadoc d'Oracle est utilisé comme base pour ce guide.
• @since est utilisé pour les classes et méthodes publiques (visibles par les développeurs de greffons) avec la révision JOSM qui a introduit l'élément. Par exemple : @since 5408.
  • @since est mis à jour / ajouté lorsqu'une signature de méthode publique change ou si une classe est renommée.
  • @since peut être omis pour les méthodes et champs publics introduits en même temps que la classe, à condition qu'ils n'aient pas été modifiés et que la classe soit correctement documentée.
  • Il peut y avoir plusieurs attributs @since - par exemple pour ajouter des interfaces à une classe. Le motif de ces attributs doit être ajouté, par exemple : @since 12345 @FunctionalIterface was added
  • Si vous soumettez un patch et que vous ne connaissez pas la révision, ajoutez de toute façon @since xxx. Elle peut ensuite être remplacée lors de la fusion de votre patch.
• @throws est préféré à @exception
• vérifiez vos changements avant le patch/commit en générant javadoc : ant javadoc, parcourez les messages de sortie ; si vous trouvez que l'exécution de javadoc est lente pour tous les fichiers, exécutez-le uniquement pour les fichiers modifiés :

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

Configuration d'Eclipse

Internationalisation

• veillez à utiliser tr(...) pour toutes les chaînes localisées

  import import static org.openstreetmap.josm.tools.I18n.tr;
  
  // utilisez tr(...) pour les messages d'exception
  //
  throw new Exception(tr("error message always in tr()"));
  
  // utilisez tr(...) pour les étiquettes, les titres, les infobulles, etc.
  //
  new JLabel(tr("Label always in tr()"));
  
  // etc.
  

• n'assemblez jamais les messages localisés avec +. Utilisez plutôt des caractères de remplacement de format à la place.

NE FAITES PAS new JLabel(tr("My Label " + labelId));

FAITES new JLabel(tr("My Label {0}",labelId));

Seule exception : + peut être utilisé pour interrompre de longues lignes de textes non variables. Les caractères de remplacement sont obligatoires dans les traductions simples.

• Lorsqu'une apostrophe est utilisée dans la chaîne de caractères source, elle doit être échappée par une autre apostrophe (comme la barre oblique inverse en C) :
  

  new JButton(tr("Don''t press me!"))
  

• Un contexte de traduction peut être défini avec trc(...). Des indications supplémentaires pour les traducteurs sont données par les commentaires java de la fonction :

  /* I18n: numéro de maison (house number), rue comme paramètre ; placer le numéro en premier pour la lisibilité. */
  msg = tr("House number {0} at {1}", s, t);
  

• Utilisez trn(...) pour laisser les traducteurs choisir le pluriel spécifique à la langue :

  msg = trn("Object deleted", "Objects deleted", del.size();
  
  // ou avec des caractères de remplacement :
  //
  new JButton(trn(/* I18n: le temps (times) est nécessaire, quelques noms (someName) comme paramètres */ 
                      "Press {1} {0} times!", n, n, someName))
  
  // La chaîne de caractères source au singulier en anglais doit être indiquée
  // à des fins d'identification, même si elle est logiquement invalide et ne 
  // se produira pas. Pour des raisons de cohérence, le caractère générique du 
  // numéro doit y être inséré.
  //
  msg = trn("Combine {0} way", "Combine {0} ways", n, n);
  

Dans les segments pluriels, aucun caractère de remplacement n'est obligatoire pour les traducteurs.

Voir également

• La version originale de cette page en anglais

---

Retour au Guide du développeur (en)