Disvolvaj Gvidlinioj

Enhavotabelo

1. Kiel via kodo devus aspekti
2. Kiel via formatado devus aspekti
3. Kiel via javadoc devus aspekti
4. Internaciigo

Kiel via kodo devus aspekti

• certigu, ke la kodo estas kongrua kun Java 11
• Dokumentu vian kodon per enliniaj komentoj kaj javadoc. Multaj homoj dankos vin :)
• Provu eviti publikajn kampojn
• JOSM havas multajn helpajn metodojn en la klasoj Utils, GuiUtils, Geometry ... Uzu ilin se vi bezonas
• Kontrolu parametrojn. Vi povas uzi Objects.requireNonNull.
• Ne skribu por efikeco - skribu por legebleco. Uzu Stream-ojn, Function-ojn kaj aliajn Java 8+ trajtojn se ili igas la kodon pli legebla.

Fadenado / Ŝlosado

• JOSM uzas diversajn ŝlosmekanismojn, depende de la objekto.
• La datumaj aroj estas protektitaj per RW-ŝloso. Kelkaj metodoj ne aŭtomate ŝlosas pro efikecaj kialoj. Certigu akiri la necesajn ŝlosojn por viaj ŝanĝoj.
• GUI-komponentoj devas esti modifitaj nur en la EDT-fadeno
• Preferu uzi SwingUtils.invokeLater se vi bezonas ruli ion en la UI-fadeno
• Multaj aŭskultantoj jam funkcias en la EDT-fadeno (tavolaj ŝanĝoj) aŭ havas centran administranton, kiu permesas al vi registri aŭskultantojn, kiuj funkcias en EDT (datumaj ŝanĝoj, elektoŝanĝoj).

Kiel via formatado devus aspekti

• certigu, ke ne estas spuroj de blanka spaco
• ne uzu multoblajn sinsekvajn malplenajn liniojn
• JOSM uzas 4-signan deŝovon kaj neniu tabo. Se vi uzas Notepad++, vi povas ŝanĝi la defaŭltan deŝovon en "Preferoj" -> "Lingvo" -> "Tabaj Agordoj" -> marku "Anstataŭigi per spacoj" (ĉi tio estas konstanta) aŭ per la butono "ŝanĝi deŝovajn agordojn" en la ilobreto (ĉi tio estas provizora agordo kaj postulas la kromprogramon "Adapti Ilobreton").
• aldonu krispajn krampojn por ĉiu if, krom se ĝi estas sekvata de return (aŭ eble throw)
• Vi devus uzi checkstyle antaŭ flikaĵo/komito: ant checkstyle kaj kontrolu checkstyle-josm.xml; se vi trovas, ke rulado de checkstyle estas malrapida por ĉiuj dosieroj, rulu nur por ŝanĝitaj dosieroj:

    # certigu, ke build2-dosierujo ekzistas, se ĝi ne ekzistas, rulu 'ant checkstyle-compile' antaŭe
  
    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
    # aŭ
    git diff --name-only | xargs \
      java -classpath "build2:tools/checkstyle/checkstyle-all.jar" \
        com.puppycrawl.tools.checkstyle.Main -c tools/checkstyle/josm_checks.xml
  

Kiel via javadoc devus aspekti

• La ​Oracle Javadoc-stilgvidilo estas uzata kiel la baza gvidilo
• @since estas uzata por publikaj klasoj kaj metodoj (videblaj al kromprogramaj programistoj) kun la JOSM-revizio, kiu enkondukis la elementon. Ekzemplo: @since 5408
  • @since estas ĝisdatigita/aldonita kiam publika metodoŝablono ŝanĝiĝas aŭ se klaso estas renomita.
  • @since povas esti preterlasita por publikaj metodoj kaj kampoj enkondukitaj samtempe kun la klaso, kondiĉe ke ili ne ŝanĝiĝis kaj la klaso estas ĝuste dokumentita.
  • Povas esti multoblaj @since-etikedo, ekz. por aldoni interfacojn al klaso. La kialo por tiuj etikedoj devas esti aldonita. Ekzemplo: @since 12345 @FunctionalIterface estis aldonita
  • Se vi sendas flikaĵon kaj ne konas la revizion, aldonu @since xxx ĉiuokaze. Ĝi povas esti anstataŭigita kiam via flikaĵo estas kunfandita.
• @throws estas preferata ol @exception
• kontrolu viajn ŝanĝojn antaŭ flikaĵo/komito per generado de javadoc: ant javadoc, foliumu elirmesaĝojn; se vi trovas, ke rulado de javadoc estas malrapida por ĉiuj dosieroj, rulu nur por ŝanĝitaj dosieroj:

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

Agordado de Eclipse

Internaciigo

• certigu, ke vi uzas tr(...) por ĉiuj lokalizitaj ĉenoj

  import import static org.openstreetmap.josm.tools.I18n.tr;
  
  // uzu tr(...) por esceptmesaĝoj
  //
  throw new Exception(tr("erarmesaĝo ĉiam en tr()"));
  
  // uzu tr(...) por etikedoj, titoloj, ilinformaj tekstoj kaj similaj
  //
  new JLabel(tr("Etikedo ĉiam en tr()"));
  
  // ktp.
  

• neniam kunmetu lokalizitajn mesaĝojn per +. Uzu formatajn anstataŭilojn anstataŭe.

NE FARU new JLabel(tr("Mia Etikedo " + labelId));

FARU new JLabel(tr("Mia Etikedo {0}",labelId));

Nur escepto: + povas esti uzata por rompi longajn liniojn de ne-variablaj tekstoj. La anstataŭiloj estas devigaj en simplaj tradukoj.

• Kiam vi uzas apostrofon en la fonta ĉeno, ĝi devas esti eskapita per alia apostrofo (kiel backslash en C):
  

  new JButton(tr("Ne premu min!"))
  

• Traduka kunteksto povas esti agordita per trc(...). Aldonaj indikoj al tradukantoj estas donitaj per java-komentoj ĉe la funkcio:

  /* I18n: domnumero, strato kiel parametro; metu numeron unue por videbleco */
  msg = tr("Domnumero {0} ĉe {1}", s, t);
  

• Uzu trn(...) por permesi al tradukantoj elekti la lingvospecifan pluralon:

  msg = trn("Objekto forigita", "Objektoj forigitaj", del.size();
  
  // aŭ kun anstataŭiloj:
  //
  new JButton(trn(/* I18n: necesaj fojoj, iu nomo kiel parametro */ 
                      "Premu {1} {0} fojojn!", n, n, someName))
  
  // La angla ununombra fonta ĉeno devas esti donita por identigo 
  // eĉ kiam ĝi estas logike nevalida kaj ne okazos. Por konsistenco 
  // la nombra anstataŭilo devas esti agordita en ĝi.
  //
  msg = trn("Kunigu {0} vojon", "Kunigu {0} vojojn", n, n);
  

En pluralaj segmentoj neniu anstataŭilo estas deviga por tradukantoj.

---

Reen al Programista Gvidilo (en)