| | 1 | [[TranslatedPages(revision=38)]] |
| | 2 | = Disvolvaj Gvidlinioj = |
| | 3 | |
| | 4 | [[PageOutline(2-2,Enhavotabelo,inline)]] |
| | 5 | |
| | 6 | == Kiel via kodo devus aspekti == |
| | 7 | |
| | 8 | * certigu, ke la kodo estas kongrua kun Java 11 |
| | 9 | * **Dokumentu** vian kodon per enliniaj komentoj kaj javadoc. Multaj homoj dankos vin :) |
| | 10 | * Provu eviti publikajn kampojn |
| | 11 | * JOSM havas multajn helpajn metodojn en la klasoj `Utils`, `GuiUtils`, `Geometry` ... Uzu ilin se vi bezonas |
| | 12 | * Kontrolu parametrojn. Vi povas uzi `Objects.requireNonNull`. |
| | 13 | * Ne skribu por efikeco - skribu por legebleco. Uzu `Stream`-ojn, `Function`-ojn kaj aliajn Java 8+ trajtojn se ili igas la kodon pli legebla. |
| | 14 | |
| | 15 | === Fadenado / Ŝlosado === |
| | 16 | |
| | 17 | * JOSM uzas diversajn ŝlosmekanismojn, depende de la objekto. |
| | 18 | * 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. |
| | 19 | * GUI-komponentoj devas esti modifitaj nur en la EDT-fadeno |
| | 20 | * Preferu uzi `SwingUtils.invokeLater` se vi bezonas ruli ion en la UI-fadeno |
| | 21 | * 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). |
| | 22 | |
| | 23 | == Kiel via formatado devus aspekti == |
| | 24 | |
| | 25 | * certigu, ke ne estas spuroj de blanka spaco |
| | 26 | * ne uzu multoblajn sinsekvajn malplenajn liniojn |
| | 27 | * 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"). |
| | 28 | * aldonu krispajn krampojn por ĉiu `if`, krom se ĝi estas sekvata de `return` (aŭ eble `throw`) |
| | 29 | * 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: |
| | 30 | {{{ |
| | 31 | #!bash |
| | 32 | # certigu, ke build2-dosierujo ekzistas, se ĝi ne ekzistas, rulu 'ant checkstyle-compile' antaŭe |
| | 33 | |
| | 34 | svn diff --summarize | awk '{ print $2 }' | grep "^[a-z]" | xargs \ |
| | 35 | java -classpath "build2:tools/checkstyle/checkstyle-all.jar" \ |
| | 36 | com.puppycrawl.tools.checkstyle.Main -c tools/checkstyle/josm_checks.xml |
| | 37 | # aŭ |
| | 38 | git diff --name-only | xargs \ |
| | 39 | java -classpath "build2:tools/checkstyle/checkstyle-all.jar" \ |
| | 40 | com.puppycrawl.tools.checkstyle.Main -c tools/checkstyle/josm_checks.xml |
| | 41 | }}} |
| | 42 | |
| | 43 | == Kiel via javadoc devus aspekti == |
| | 44 | * La [https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide Oracle Javadoc-stilgvidilo] estas uzata kiel la baza gvidilo |
| | 45 | * `@since` estas uzata por publikaj klasoj kaj metodoj (videblaj al kromprogramaj programistoj) kun la JOSM-revizio, kiu enkondukis la elementon. Ekzemplo: `@since 5408` |
| | 46 | * `@since` estas ĝisdatigita/aldonita kiam publika metodoŝablono ŝanĝiĝas aŭ se klaso estas renomita. |
| | 47 | * `@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. |
| | 48 | * 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` |
| | 49 | * 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. |
| | 50 | * `@throws` estas preferata ol `@exception` |
| | 51 | * 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: |
| | 52 | |
| | 53 | {{{ |
| | 54 | svn diff --summarize | awk '{ print $2 }' | xargs javadoc -d javadoc |
| | 55 | # aŭ |
| | 56 | git diff --name-only | xargs javadoc -d javadoc |
| | 57 | }}} |
| | 58 | |
| | 59 | === Agordado de Eclipse === |
| | 60 | [[Image(DevelopersGuide/StyleGuide:styleguide_compiler_16.png,700px)]] |
| | 61 | |
| | 62 | [[Image(DevelopersGuide/StyleGuide:ss1.png,700px)]] |
| | 63 | |
| | 64 | [[Image(DevelopersGuide/StyleGuide:ss2.png,700px)]] |
| | 65 | |
| | 66 | [[Image(DevelopersGuide/StyleGuide:ss3.png,700px)]] |
| | 67 | |
| | 68 | |
| | 69 | == Internaciigo == |
| | 70 | |
| | 71 | * certigu, ke vi uzas `tr(...)` por ĉiuj lokalizitaj ĉenoj |
| | 72 | {{{ |
| | 73 | #!java |
| | 74 | import import static org.openstreetmap.josm.tools.I18n.tr; |
| | 75 | |
| | 76 | // uzu tr(...) por esceptmesaĝoj |
| | 77 | // |
| | 78 | throw new Exception(tr("erarmesaĝo ĉiam en tr()")); |
| | 79 | |
| | 80 | // uzu tr(...) por etikedoj, titoloj, ilinformaj tekstoj kaj similaj |
| | 81 | // |
| | 82 | new JLabel(tr("Etikedo ĉiam en tr()")); |
| | 83 | |
| | 84 | // ktp. |
| | 85 | }}} |
| | 86 | |
| | 87 | * neniam kunmetu lokalizitajn mesaĝojn per `+`. Uzu formatajn anstataŭilojn anstataŭe. |
| | 88 | |
| | 89 | **NE FARU** |
| | 90 | `new JLabel(tr("Mia Etikedo " + labelId));` |
| | 91 | |
| | 92 | **FARU** |
| | 93 | `new JLabel(tr("Mia Etikedo {0}",labelId));` |
| | 94 | |
| | 95 | Nur escepto: `+` povas esti uzata por rompi longajn liniojn de ne-variablaj tekstoj. |
| | 96 | La anstataŭiloj estas devigaj en simplaj tradukoj. |
| | 97 | |
| | 98 | * Kiam vi uzas apostrofon en la fonta ĉeno, ĝi devas esti eskapita per alia apostrofo (kiel backslash en C):[[BR]] |
| | 99 | {{{#!java |
| | 100 | new JButton(tr("Ne premu min!")) |
| | 101 | }}} |
| | 102 | |
| | 103 | * Traduka kunteksto povas esti agordita per `trc(...)`. Aldonaj indikoj al tradukantoj estas donitaj per java-komentoj ĉe la funkcio: |
| | 104 | {{{#!java |
| | 105 | /* I18n: domnumero, strato kiel parametro; metu numeron unue por videbleco */ |
| | 106 | msg = tr("Domnumero {0} ĉe {1}", s, t); |
| | 107 | }}} |
| | 108 | |
| | 109 | * Uzu `trn(...)` por permesi al tradukantoj elekti la lingvospecifan pluralon: |
| | 110 | {{{#!java |
| | 111 | msg = trn("Objekto forigita", "Objektoj forigitaj", del.size(); |
| | 112 | |
| | 113 | // aŭ kun anstataŭiloj: |
| | 114 | // |
| | 115 | new JButton(trn(/* I18n: necesaj fojoj, iu nomo kiel parametro */ |
| | 116 | "Premu {1} {0} fojojn!", n, n, someName)) |
| | 117 | |
| | 118 | // La angla ununombra fonta ĉeno devas esti donita por identigo |
| | 119 | // eĉ kiam ĝi estas logike nevalida kaj ne okazos. Por konsistenco |
| | 120 | // la nombra anstataŭilo devas esti agordita en ĝi. |
| | 121 | // |
| | 122 | msg = trn("Kunigu {0} vojon", "Kunigu {0} vojojn", n, n); |
| | 123 | }}} |
| | 124 | |
| | 125 | En pluralaj segmentoj neniu anstataŭilo estas deviga por tradukantoj. |
| | 126 | |
| | 127 | ---- |
| | 128 | Reen al [wikitr:/DevelopersGuide Programista Gvidilo] |
