Elemzői kommentek írása

Ez a dokumentum információkat és irányelveket ad arról, hogyan írjuk meg az elemző által előállított megjegyzéseket.

Tartalom

Az elemzői megjegyzések tartalma Markdown-dokumentumként a exercism/website-copy repóban található. A megjegyzések tartalmaznak egy mutató sztringet <track-slug>.<exercise-slug>.<comment-slug> formátumban, amely egy adott Markdown-dokumentumra mutat a website-copy repóban.

Például a ruby.two-fer.string-interpolation a https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md oldalra mutat.

Megfogalmazás

• Kerüld a szükségtelenül bőbeszédű megjegyzéseket. Fogalmazz tömören.
• Maradj semlegesen megfigyelő; kerüld a töltettel teli és az általánosító kijelentéseket.
• A javaslatot fogalmazd meg egyértelműen.
• Ha lehet, előbb a javaslat kerüljön előre, és csak utána a magyarázat.
• Kerüld a „me”, az „I”, a „we” stb. használatát, mert a bot nem személy.
• Kerüld a „you” és a „your code” használatát, mert ez néha úgy hathat, mintha az illetőt ítélné meg, nem a kódot.
• Kerüld az olyan szavakat, mint a „just”, a „simply” és az „obviously”, mert ezek lekezelőnek hathatnak: ha a megjegyzés szükséges, akkor az obviously nem volt obvious.
• Kerüld a feltételezéseket arról, hogy az emberek mit tudnak, és mit nem. Az egyetlen kivétel a már befejezett alapvető feladatokból származó tudás. Kerüld az „as you know”, „as you remember”, „as you learned”, „now that we all understand x” fordulatokat, mert hiába mondtunk el valamit, az illető még nem feltétlenül érti meg.

Útmutatás

• A gördülékenységre törekedj, ne a jártasságra: az Exercism egy nyelvi kurzusának célja, hogy az emberek alacsony jártassági szinten is magas szintű gördülékenységet érjenek el. A cél a gördülékenység a nyelv szintaxisában, idiómáiban és szabványos könyvtárában.
• Lehetőleg idiomatikus kódot javasolj, ahol az idiomatikus azt jelenti, hogy a kódot szinte minden fejlesztő megírná, aki abban a nyelvben dolgozik (és nem hobbi szinten űzi). Ha nem idiomatikus javaslatot teszel, említsd meg ezt, és magyarázd el, miért lehet a javaslat mégis hasznos.
• Nevezd meg a különbséget aközött, amit az illető csinál, és ami az adott nyelvben „idiomatikus”.
• Használd a megfelelő kifejezéseket és elnevezéseket, hogy az emberek máshol is felismerjék ezeket a fogalmakat, és maguk is utána tudjanak nézni.
• Ne add meg a megoldást; ez általános érvényű tanács az Exercism minden mentorálásában. A tanulás akkor rögzül igazán, ha az ember maga fedezi fel a választ. Ez óriási élmény, és az érzelmi löket teszi emlékezetessé. Ha azonban a felfedezés nem vált ki dopaminlöketet, akkor teljesen logikus megmutatni, hogyan is néz ki a megoldás. Például egy jóváhagyott megoldáshoz fűzött apró javítás sokkal kevésbé izgalmas, mint egy tanulási pont megfogalmazása egy olyan megoldásnál, amelyet épp elutasítunk, és ezért ott talán inkább egy példa indokolt, mint egy link.
• Az észrevételeket fontossági sorrendben add meg, az első megjegyzés legyen a legfontosabb, az utolsó a legkevésbé fontos.
• Tartsd kezelhető számban a megjegyzéseket. Egy iterációhoz egy-három megjegyzést célozz meg.
• Ne írd le ugyanazt a megjegyzést kétszer egy elemzésben. Ha ugyanazt a megjegyzést más paraméterekkel adod hozzá, az nem számít duplikátumnak.
• Fontold meg, hogy csak a formázásról írsz megjegyzést, ha a formázás vagy a lintelés szerves része a nyelvnek. Ha lehet, irányítsd a tanulókat automatikus formázó eszközök felé, és/vagy linkelj a hivatalos stílusútmutatóra.

Első néhány feladat

Egy kurzus első néhány feladatánál a következők különösen fontosak:

• Legyen viszonylag rövid, kerüld a szövegfalfalat, és ne árasszd el őket tanácsokkal. Ha jó élményben van része az első feladatban, visszatér, és még rengeteg lehetőséged lesz visszajelzést adni mindarról, amit észrevettél.
• Ne magyarázz el túlzottan egy fogalmat: ne menj bele mélyen a fordítók mögöttes mechanizmusaiba meg hasonlókba. Itt inkább arról van szó, hogy ez a nyelvi kurzus egyik első feladata, és ebben a szakaszban a visszajelzés akkor a leghasznosabb, ha rövidebb és iránymutatóbb jellegű.
• Adj egy linket, amely pontosan megmutatja, hogyan kell az adott fogalmat csinálni, tutorial jellegűen. Vagyis: megmutatja, hogyan csináljuk a dolgokat, és nem arról beszél, miért. Ez azt is jelentheti, hogy a nyelv hivatalos dokumentációja nem elég, mert az gyakran kódreferencia, és nem mutatja meg, hogyan használjuk, és hogyan működik. Ugyanakkor linket csak a mélyebb felfedezéshez adj. A tanulónak közvetlenül a válaszból kell megértenie, mire gondolsz, anélkül, hogy követné a linket.

Példák

JavaScriptben egy tanuló let-tel írt meg egy legfelső szintű konstanst.

<!-- not following these guidelines -->

As you know, everyone uses const, you shouldn't use let or var.

Ez a megjegyzés a következő okok miatt nem követi ezeket az irányelveket:

• A cselekvés a „magyarázat” után következik.
• „As you know”: nem tudjuk, hogy a tanuló tudja-e.
• „you shouldn't”: nincs szükség a „you” szóra ahhoz, hogy ezt kijelentsd.
• „everyone uses const”: ez nem igaz, és azt érezheti tőle a tanuló, hogy valami borzalmasat rontott el.
• Hiányzik a valódi magyarázat arról, miért hangzik el a tanács.

<!-- better -->

Prefer `const` and `let` over `var`. The `const` declaration stops a variable
from being accidentally reassigned, which provides safety, and reduces
cognitive load for someone reading the code. [This article](https://medium.com/javascript-scene/javascript-es6-var-let-or-const-ba58b8dcde75)
explains the difference between the three.

Go-ban egy tanuló egyéni hibát hozott létre a beépítettek helyett:

<!-- not following these guidelines -->

I see you are creating a custom `error`. This is perfectly fine! If you did not
know about `errors.New` and `fmt.Errorf` have a look at them as they are much
simpler ways to create an error. Custom errors are helpful if you want to check
if an error is of a certain type later.

Ez a megjegyzés a következő okok miatt nem követi ezeket az irányelveket:

• „I see”: az elemző nem személy: kerüld az „I” használatát.
• „This is perfectly fine!”: látszólag mégsem az, különben nem lett volna szükség a megnyugtatásra. Ezt valószínűleg teljesen el is lehet hagyni; ha valami létező dologról szeretnél általános tippet adni, pont ezt mondhatod: „An alternative, equally valid way of doing x is y.”
• „If you did not know about”: hagyd ki ezt a túlzottan terjengős szócsoportot.

<!-- better -->

A custom `error` is typically used to provide custom behavior, or to distinguish
on type later. For simpler cases, it's more common to rely on `errors.New` or
`fmt.Errorf`. This [in-depth article](https://golangbot.com/custom-errors/) about
custom errors might be interesting.

CI

Mivel a megjegyzések nem ugyanabban a repóban találhatók, mint az elemző, minden elemzőhöz tartoznia kell olyan CI-nak, amely ellenőrzi, hogy az adott elemzőben használt megjegyzések (azok, amelyek kimenetté válhatnak) az exercism/website-copy repó main ágán lévő megjegyzések-e.

A dokumentum írásakor ez az issue követi nyomon, hogy van-e egyáltalán általánosítása ennek a CI-nak.