|
| 1 | +--- |
| 2 | +slug: /contributing/coding-standards |
| 3 | +title: Emisingi gy'Empandiika ya Koodi |
| 4 | +description: Jino jilambika ku mpandiika ya koodi mu playground era gyogera ku bubaka obujja nga waliwo ensobi, API y'olukale, Ebizimbe ebilaborwako. |
| 5 | +--- |
| 6 | + |
| 7 | +# Emisingi gy'Empandiika ya Koodi |
| 8 | + |
| 9 | +<!-- |
| 10 | +# Coding principles |
| 11 | +--> |
| 12 | + |
| 13 | +## Obubaka nga waliwo Ensobi |
| 14 | + |
| 15 | +<!-- |
| 16 | +## Error messages |
| 17 | +--> |
| 18 | + |
| 19 | +Obubaka obujja nga waliwo ensobi obulungi butegeeza omukozesa omutendera ogw'okugoberera. Ensobi yonna etategeerekeka mu Playground [Public APIs](/developers/apis/) ejja kuwaliriza abakozi okulopa ensobi |
| 20 | + |
| 21 | +<!-- |
| 22 | +A good error message informs the user of the following steps to take. Any ambiguity in errors thrown by Playground [Public APIs](/developers/apis/) will prompt the developers to open issues. |
| 23 | +--> |
| 24 | + |
| 25 | +Twalowooza ku nsobi y'omukutu gw'omutimbagano, okugeza—tusobola okuteebereza ekika ky'ensobi n'okulaga obubaka obukwatagana nga twongera ku mutendera oguddako? |
| 26 | + |
| 27 | +<!-- |
| 28 | +Consider a network error, for example—can we infer the type of error and display a relevant message summarizing the next steps? |
| 29 | +--> |
| 30 | + |
| 31 | +- **Ensobi y'omukutu gw'omutimbagano**: "Omukutu gw'omutimbagano gwo guweddemu. Gezaako okuzzaamu olupapula. |
| 32 | +- **404**: "Fayiro tekirabiddwa". |
| 33 | +- **403**: "Seva ewanise okuyingira mu fayiro". |
| 34 | +- **CORS**: Nnyonnyola nti kye kikola ekirinda mu browza era ongereyo link egenda ku nnyonnyola entuufu (ku MDN oba ensibuko endala eya kukkirizibwa). Kuwa omukozesa amagezi okukyusa fayiro ye okugitwala mu kifo ekirala, nga `raw.githubusercontent.com`, era ongereyo link ku nsibuko ennyonnyola engeri y'okuteeka CORS headers ku seva zaabwe. |
| 35 | + |
| 36 | +<!-- |
| 37 | +- **Network error**: "Your internet connection twitched. Try to reload the page. |
| 38 | +- **404**: "Could not find the file". |
| 39 | +- **403**: "The server blocked access to the file". |
| 40 | +- **CORS**: clarify it's a browser security feature and add a link to a detailed explanation (on MDN or another reliable source). Suggest the user move their file somewhere else, like `raw.githubusercontent.com`, and link to a resource explaining how to set up CORS headers on their servers. |
| 41 | +--> |
| 42 | + |
| 43 | +Tukwata okutereeza koodi n'okukola linting mu ngeri ey'otomatiiki. Wummule, wandiika, era leka ebyuma bikole omulimu. |
| 44 | + |
| 45 | +<!-- |
| 46 | +We handle code formatting and linting automatically. Relax, type away, and let the machines do the work. |
| 47 | +--> |
| 48 | + |
| 49 | +## Public API |
| 50 | + |
| 51 | +<!-- |
| 52 | +## Public API |
| 53 | +--> |
| 54 | + |
| 55 | +Playground eruubirira okukuuma API scope ennono ennyo. |
| 56 | + |
| 57 | +<!-- |
| 58 | +Playground aims to keep the narrowest possible API scope. |
| 59 | +--> |
| 60 | + |
| 61 | +Public APIs zi yangu okuziyongera naye nzizibu okuziggyawo. Kyetaaga PR emu okuyingiza API empya, naye kiyinza okwetaaga lukumi okugigyawo, naddala singa pulojekiti endala zizikozesezza dda. |
| 62 | + |
| 63 | +<!-- |
| 64 | +Public APIs are easy to add and hard to remove. It only takes one PR to introduce a new API, but it may take a thousand to remove it, especially if other projects have already consumed it. |
| 65 | +--> |
| 66 | + |
| 67 | +- Tolaga functions, classes, constants, oba components endala eziteetaagisa. |
| 68 | + |
| 69 | +<!-- |
| 70 | +- Don't expose unnecessary functions, classes, constants, or other components. |
| 71 | +--> |
| 72 | + |
| 73 | +## Enteekateeka |
| 74 | + |
| 75 | +<!-- |
| 76 | +## Blueprints |
| 77 | +--> |
| 78 | + |
| 79 | +[Enteekateeka](/blueprints/getting-started) ze ngeri enkulu ey'okukolagana ne Playground. Fayiro zino za JSON zinnyonnyola emitendo egy'emitendera Playground gy'ekola mu nkola. |
| 80 | + |
| 81 | +<!-- |
| 82 | +[Blueprints](/blueprints/getting-started) are the primary way to interact with Playground. These JSON files describe a set of steps that Playground executes in order. |
| 83 | +--> |
| 84 | + |
| 85 | +### Ebiragiro |
| 86 | + |
| 87 | +<!-- |
| 88 | +### Guidelines |
| 89 | +--> |
| 90 | + |
| 91 | +Emitendera gy'enteekateeka girina okuba **migufu era egy'omusingi**. Girina okukola kinumu era okukikola obulungi. |
| 92 | + |
| 93 | +<!-- |
| 94 | +Blueprint steps should be **concise and focused**. They should do one thing and do it well. |
| 95 | +--> |
| 96 | + |
| 97 | +- Bw'oba oyagala okukola omutendera omupya, sooka okugezaako okudda okutereeza ogw'awali. |
| 98 | +- Bw'ekyo tekimala, kakasa nti omutendera omupya guleeta obusobozi obupya. Toddamu kukola functions ez'emitendera egy'awali. |
| 99 | +- Lowooza nti omutendera gujja kuyitibwa emirundi egisinga emu. |
| 100 | +- Lowooza nti gujja kukola mu nkola entongole. |
| 101 | +- Yongera unit tests okukakasa ekyo. |
| 102 | + |
| 103 | +<!-- |
| 104 | +- If you need to create a new step, try refactoring an existing one first. |
| 105 | +- If that's not enough, ensure the new step delivers a new capability. Don't replicate the functionality of existing steps. |
| 106 | +- Assume the step would be called more than once. |
| 107 | +- Assume it would run in a specific order. |
| 108 | +- Add unit tests to verify that. |
| 109 | +--> |
| 110 | + |
| 111 | +Enteekateeka zirina okuba **ez'amanyi era ez'eyangu okutegeerera**. |
| 112 | + |
| 113 | +<!-- |
| 114 | +Blueprints should be **intuitive and straightforward**. |
| 115 | +--> |
| 116 | + |
| 117 | +- Tosabanga arguments ezisobola okuba optional. |
| 118 | +- Kozesa argument ennyangu. Okugeza, `slug` mu kifo kya `path`. |
| 119 | +- Nnyonnyola constants mu virtual JSON files—tolongoosa PHP files. |
| 120 | +- Nnyonnyola TypeScript type ku Blueprint. Bw'etyo Playground bw'ekola JSON schema yaayo. |
| 121 | +- Wandiika function okukwata omutendera gwa Blueprint. Kkiriza argument ey'ekika ky'onnyonnyodde. |
| 122 | +- Waayo ekyokulabirako eky'okukozesa mu doc string. Ekyeraga mu ngeri ey'otomatiiki mu biwandiiko. |
| 123 | + |
| 124 | +<!-- |
| 125 | +- Don't require arguments that can be optional. |
| 126 | +- Use plain argument. For example, `slug` instead of `path`. |
| 127 | +- Define constants in virtual JSON files—don't modify PHP files. |
| 128 | +- Define a TypeScript type for the Blueprint. That's how Playground generates its JSON schema. |
| 129 | +- Write a function to handle a Blueprint step. Accept the argument of the type you defined. |
| 130 | +- Provide a usage example in the doc string. It's automatically reflected in the docs. |
| 131 | +--> |
0 commit comments