wiki:Eo:DevelopersGuide/StyleGuide

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)

Last modified 5 months ago Last modified on 2025-03-08T21:43:42+01:00
Note: See TracWiki for help on using the wiki.