Context Navigation

Editing Eo:DevelopersGuide/StyleGuide

Adjust edit area height: Edit side-by-side

[[TranslatedPages(revision=38)]]
= Disvolvaj Gvidlinioj =

[[PageOutline(2-2,Enhavotabelo,inline)]]

== 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:
{{{
  #!bash
    # 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 [https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide 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 ===
[[Image(DevelopersGuide/StyleGuide:styleguide_compiler_16.png,700px)]]

[[Image(DevelopersGuide/StyleGuide:ss1.png,700px)]]

[[Image(DevelopersGuide/StyleGuide:ss2.png,700px)]]

[[Image(DevelopersGuide/StyleGuide:ss3.png,700px)]]

== Internaciigo ==

* certigu, ke vi uzas `tr(...)` por ĉiuj lokalizitaj ĉenoj
   {{{
   #!java
   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):[[BR]]
   {{{#!java
   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:
   {{{#!java
   /* 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:
   {{{#!java
   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 [wikitr:/DevelopersGuide Programista Gvidilo]

Note: See WikiFormatting and TracWiki for help on editing wiki content.

Change information

Your email or username:

E-mail address and name can be saved in the Preferences

Comment about this change (optional):

Note: See TracWiki for help on using the wiki.