Οδηγίες Ανάπτυξης

Table of content

1. Πώς θα πρέπει να είναι ο κώδικάς σας
2. Πώς θα πρέπει να είναι η μορφοποίηση του κώδικά σας
3. Πώς πρέπει να φαίνεται το javadoc σας
4. Διεθνοποίηση

Πώς θα πρέπει να είναι ο κώδικάς σας

• Βεβαιωθείτε ότι ο κώδικας είναι συμβατός με Java 11
• Τεκμηριώστε τον κώδικά σας χρησιμοποιώντας ενσωματωμένα σχόλια και javadoc. Πολλοί άνθρωποι θα σας ευγνωμονούν :)
• Προσπαθήστε να αποφύγετε τα δημόσια πεδία
• Το JOSM περιλαμβάνει πολλές βοηθητικές μεθόδους στις κλάσεις Utils, GuiUtils, Geometry .... Χρησιμοποιήστε τις αν χρειάζεστε
• Ελέγξτε τις παραμέτρους. Μπορείτε να χρησιμοποιήσετε το Objects.requireNonNull.
• Μην γράφετε για απόδοση - γράψτε για αναγνωσιμότητα. Χρησιμοποιήστε Streams, Functions και άλλες λειτουργίες Java 8+ αν κάνουν τον κώδικα πιο ευανάγνωστο.

Threading / Κλείδωμα

• Το JOSM χρησιμοποιεί διάφορους μηχανισμούς κλειδώματος, ανάλογα με το αντικείμενο.
• Τα σύνολα δεδομένων προστατεύονται από κλείδωμα RW. Ορισμένες μέθοδοι δεν κλειδώνουν αυτόματα για λόγους απόδοσης. Βεβαιωθείτε ότι έχετε αποκτήσει τα κλειδώματα που απαιτούνται για τις αλλαγές σας.
• Τα στοιχεία GUI θα πρέπει να τροποποιούνται μόνο στο νήμα EDT.
• Προτιμήστε να χρησιμοποιείτε τη μέθοδο SwingUtils.invokeLater εάν χρειάζεται να εκτελέσετε οτιδήποτε στο νήμα UI.
• Πολλοί ακροατές εκτελούνται ήδη στο νήμα EDT (αλλαγές επιπέδων) ή έχουν έναν κεντρικό διαχειριστή που σας επιτρέπει να καταχωρείτε ακροατές που εκτελούνται στο EDT (αλλαγές συνόλου δεδομένων, αλλαγές επιλογής).

Πώς θα πρέπει να είναι η μορφοποίηση του κώδικά σας

• βεβαιωθείτε ότι δεν υπάρχουν κενά διαστήματα στο τέλος των γραμμών
• μην χρησιμοποιείτε πολλαπλές συνεχόμενες κενές γραμμές
• το JOSM χρησιμοποιεί εσοχή 4 χαρακτήρων και καθόλου στηλοθέτες. Εάν χρησιμοποιείτε το Notepad++ μπορείτε να αλλάξετε την προεπιλεγμένη εσοχή στις "Προτιμήσεις" -> "Γλώσσα" -> "Ρυθμίσεις στηλοθέτη" -> επιλέξτε "Αντικατάσταση με κενά" (αυτό είναι μόνιμο) ή με το κουμπί "αλλαγή ρυθμίσεων εσοχής" στη εργαλειοθήκη (αυτή είναι μια προσωρινή ρύθμιση και απαιτεί το πρόσθετο "Προσαρμογή Εργαλειοθήκης").
• προσθέστε αγκύλες για κάθε if, εκτός εάν ακολουθείται από return (ή πιθανώς throw)
• Θα πρέπει να χρησιμοποιήσετε το checkstyle πριν από το patch/commit: ant checkstyle και ελέγξτε checkstyle-josm.xml; εάν διαπιστώσετε ότι η εκτέλεση του checkstyle είναι αργή για όλα τα αρχεία, εκτελέστε την μόνο για τα τροποποιημένα αρχεία:

    # 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
  

Πώς πρέπει να φαίνεται το javadoc σας

• Ο ​οδηγός στυλ Oracle Javadoc χρησιμοποιείται ως βασικός οδηγός
• Το @since χρησιμοποιείται για δημόσιες κλάσεις και μεθόδους (ορατές στους προγραμματιστές πρόσθετων) με την έκδοση JOSM που εισήγαγε το στοιχείο. Παράδειγμα: @since 5408
  • Το @since ενημερώνεται / προστίθεται όταν αλλάζει η υπογραφή μιας δημόσιας μεθόδου ή εάν μετονομαστεί μια κλάση.
  • Το @since μπορεί να παραλειφθεί για δημόσιες μεθόδους και πεδία που εισάγονται ταυτόχρονα με την κλάση, υπό την προϋπόθεση ότι δεν έχουν αλλάξει και η κλάση είναι σωστά τεκμηριωμένη.
  • Μπορεί να υπάρχουν πολλαπλές ετικέτες @since tags, e.g. fπ.χ. για την προσθήκη διεπαφών σε μια κλάση. Ο λόγος για αυτές τις ετικέτες πρέπει να προστεθεί Παράδειγμα: @since 12345 @FunctionalIterface προστέθηκε
  • Εάν υποβάλετε μια ενημέρωση κώδικα και δεν γνωρίζετε την έκδοση κώδικα, προσθέστε το @since xxx έτσι κι αλλιώς. Μπορεί στη συνέχεια, να αντικατασταθεί κατά τη συγχώνευση της ενημέρωσης κώδικα.
• Το @throws προτιμάται από το @exception
• ελέγξτε τις αλλαγές σας πριν από την ενημέρωση κώδικα/επικύρωση δημιουργώντας javadoc: ant javadoc, browse output messages; Αν διαπιστώσετε ότι η εκτέλεση του javadoc είναι αργή για όλα τα αρχεία, εκτελέστε το μόνο για τα τροποποιημένα αρχεία:

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

Ρύθμιση του Eclipse

Διεθνοποίηση

• Βεβαιωθείτε ότι χρησιμοποιείτε το tr(...) για όλες τις μεταφραζόμενες συμβολοσειρές

  import import static org.openstreetmap.josm.tools.I18n.tr;
  
  // use tr(...) for exception messages
  //
  throw new Exception(tr("error message always in tr()"));
  
  // use tr(...) for labels, title, tooltip texts and the like
  //
  new JLabel(tr("Label always in tr()"));
  
  // etc.
  

• μην συναρμολογείτε μεταφρασμένα μηνύματα με +. Χρησιμοποιήστε ειδικούς χαρακτήρες αντικατάστασης.

ΜΗΝ new JLabel(tr("My Label " + labelId));

ΚΑΝΤΕ ΤΟ new JLabel(tr("My Label {0}",labelId));

Μοναδική εξαίρεση: Το + μπορεί να χρησιμοποιηθεί για να διακόψει μεγάλες γραμμές μη μεταβλητών κειμένων. Οι ειδικοί χαρακτήρες αντικατάστασης είναι υποχρεωτικοί σε απλές μεταφράσεις.

• Όταν χρησιμοποιείτε απόστροφο μέσα σε μεταφράσιμη συμβολοσειρά, πρέπει να διαφεύγει με μία δεύτερη απόστροφο (όπως το backslash στην C):
  

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

• Ένα περιβάλλον μετάφρασης μπορεί να οριστεί με trc(...). Πρόσθετες συμβουλές για τους μεταφραστές δίνονται από σχόλια java στη συνάρτηση:

  /* I18n: house number, street as parameter; place number first for visibility */
  msg = tr("House number {0} at {1}", s, t);
  

• Χρησιμοποιήστε trn(...) για να επιτρέψετε στους μεταφραστές να επιλέξουν τον πληθυντικό για τη συγκεκριμένη γλώσσα:

  msg = trn("Object deleted", "Objects deleted", del.size();
  
  // or with placeholders:
  //
  new JButton(trn(/* I18n: times needed, some name as parameter */ 
                      "Press {1} {0} times!", n, n, someName))
  
  // The English singular source string must be given for identification 
  // even when its logically invalid and won't occur. For consistency 
  // the number placeholder should be set in it.
  //
  msg = trn("Combine {0} way", "Combine {0} ways", n, n);
  

Στα τμήματα πληθυντικού δεν είναι υποχρεωτικοί οι ειδικοί χαρακτήρες αντικατάστασης για τους μεταφραστές.

---

Πίσω στο Οδηγός για Προγραμματιστές (en)