Daily Work

Communication

I am only responsible for what I said, not for what you understood

Igaz ez? Miért nem?

Számítsd bele, hogy a másik nem ugyanazzokkal az előismeretekkel rendelkezik, nem ugyanazzal a fogalomkészlettel, terminológiával, esetleg anyanyalvvel.

Requirement Engineering

Coding

A TDD-ről részletesen a TDD fejezetben.

Cserkész szabály

Always leave the campground cleaner than you found it

-- Robert C. Martin (Uncle Bob)

Clean Code

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability. source

A viccet félretéve az egész lényege az érthetőség és a karbantarthatóság. Két hét múlva is meg kell értened a saját kódod és nem csak neked.

Meaningful Names

Az alábbiak Robert C. Martin Clean Code című könyvénből a 2. fejezet (Meaningful Names) alfejezet címei, az idézetek is onnan valók.

  • Use Intention-Revealing Names

    • int d; // elapsed time in days

    • int elapsedTimeInDays;

  • Avoid Disinformation
  • Make Meaningful Distinctions

    • It is not sufficient to add number series or noise words, even though the compiler is satisfied. If names must be different, then they should also mean something different.

  • Use Pronounceable Names

    • If you can’t pronounce it, you can’t discuss it without sounding like an idiot. “Well, over here on the bee cee arr three cee enn tee we have a pee ess zee kyew int, see?”

    • Külön szempont ez nem angol anyanelyvűeknél, némely szavakat bonyolultabb kiejtenünk
  • Use Searchable Names

    • Single-letter names can ONLY be used as local variables inside short methods. The length of a name should correspond to the size of its scope.

  • Avoid Mental Mapping

    • Readers shouldn’t have to mentally translate your names into other names they already know.

    • clarity is king

  • Avoid Encodings
    • a modern IDE-k esetében már teljesen fölösleges típus vagy szerepjelöléseket tenni a nevekbe
  • Pick One Word per Concept
  • Don’t Pun or use humor
  • Add Meaningful Context

    • Imagine that you have variables named firstName, lastName, street, houseNumber, city, state, and zipcode. Taken together it’s pretty clear that they form an address. But what if you just saw the state variable being used alone in a method?

Nincs megjelölve forrás, de ez az összefogleló is ezen a fejezeten alapszik.

Functions

Az alábbiak Robert C. Martin Clean Code című könyvénből a 3. fejezetén alapulnak.

  • A hossza legyen a lehető legrövidebb (akár 2-4 sor, bár személy szerint azt néha túlzásnak tartom)
  • Do One Thing
  • Use Descriptive Names
    • egy metódus valamit csinál, tehát kezdődjön igével, pl. increaseSpeed
    • a nevéből legyen egyértelmű, hogy mit csinál

    • Robert C. Martin The Inverse Scope Law of Function Names: The longer the scope of a function, the shorter its name should be. Functions that are called locally from a few nearby places should have long descriptive names, and the longest function names should be given to those functions that are called from just one place.

  • Function Arguments
    • Lehetőleg ne használj 3-nál több paramétert

    • Flag arguments are ugly [...] loudly proclaiming that this function does more than one thing.

  • Have No Side Effects

    • Wikipédiából: an operation, function or expression is said to have a side effect if it modifies some state variable value(s) outside its local environment, that is to say has an observable effect besides returning a value (the main effect) to the invoker of the operation.

    • Side effects are lies. Your function promises to do one thing, but it also does other hidden things.

  • Prefer Exceptions to Returning Error Codes
    • a korábbiakból már adódik, hogy miért jobb egy FileNotFoundException mint egy ERRCODE_26375

Comments

One of the more common motivations for writing comments is bad code. We write a module and we know it is confusing and disorganized. We know it’s a mess. So we say to ourselves, “Ooh, I’d better comment that!” No! You’d better clean it!

-- Robert C. Martin: Clean Code, pp 55.

  • Gyakori a kód strukturálása kommentekkel, ilyenkor célszerű függvényeket használni inkább
  • Kerülendő a TODO és a FIXME a kommentekben, ez azt jelenti, hogy nem vagy készen
  • Kommentezni ajánlott viszont -szerintem- a domain specifikus részeket, amelyek megértését nem feltétlenül lehet elvárni egy fejlesztőtől. Pl. egy fizikai számítás.
  • Továbbá nem haszontalan a dokumentációs kommentezés pl. Javadoc, kivéve ha egy increaseSpeed metódus kommentje annyi, hogy "this method increases the speed", sokkal többet mondana az, hogy mennyivel, milyen korlátok között stb. amelyek révén aztán hasznos lesz a generált API dokumentáció anélkül, hogy a kódba kellene nézni.

Verziókezelők

Mi a verziókezelő?

Version control, a.k.a. revision control / source code management, is basically a system for recording and managing changes made to files and folders. It is commonly used to manage source code, however, it is also well suited to tracking changes to any kind of file which contains mostly text.

-- forrás

Az ember hajlamos ad-hoc módon is verziózni a munkáját, pl.1:

Több szolgáltatás és szoftver alapból tartalmaz verziókövetést, pl. a Dropbox, Google Drive, stb. is verziózza a feltöltött állományokat; az MS Word még merge-elni is tudja az egyes verziókat.

Michael Ernst összefoglalója alapján:

  • Version control enables multiple people to simultaneously work on a single project. Each person edits his or her own copy of the files and chooses when to share those changes with the rest of the team. Thus, temporary or partial edits by one person do not interfere with another person's work.
  • Version control also enables one person you to use multiple computers to work on a project, so it is valuable even if you are working by yourself.
  • Version control integrates work done simultaneously by different team members. In most cases, edits to different files or even the same file can be combined without losing any work. In rare cases, when two people make conflicting edits to the same line of a file, then the version control system requests human assistance in deciding what to do.
  • Version control gives access to historical versions of your project. This is insurance against computer crashes or data lossage. If you make a mistake, you can roll back to a previous version. You can reproduce and understand a bug report on a past version of your software. You can also undo specific edits without losing all the work that was done in the meanwhile. For any part of a file, you can determine when, why, and by whom it was ever edited.

Mit érdemes verziókezelni

"In practice, everything that has been created manually should be put in version control, including programs, original field observations, and the source files for papers."

-- Best Practices for Scientific Computing; Wilson et al. 2012 (arXiv:1210.0530)

Az ehhez a jegyzethez készített ábrák és azok forrása is verziókezelés alatt van, ezek a .png és .dia állományok a /src/images/ mappában, utóbbiak valójában egy diagramszerkesztő alkalmazás XML alapú forrásfájljai.

  • Ez az írás összefoglalja a verziókezelési modelleket (Lock-Modify-Unlock, Copy-Modify-Merge), emez pedig összehasonlítja a centralizált és az elosztott verziókezelőket.
  • About Version Control
    • a Git könyv első fejezete, rövid összefoglaló
  • gyakorlati oldalról lást Git fejezet
1

http://smutch.github.io/VersionControlTutorial/pages/0-intro.html#what-is-version-control

Centralizált verziókezelő

centralized_version_control

Elosztott verziókezelő

distributed_version_control

Branching

A félév során a GitHubFlow-t használjuk, részletek a GitHub fejezetben.

Commit üzenetek

xkcd 1296

A How to Write a Git Commit Message egy hosszabb, példákkal illusztrált írás a jó commit üzenetekről, amely hét szabályban foglalja össze, hogy mire kell figyelni. Ezt egészíteném ki egy nyolcadikkal.

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
    • ez a legkevésbé fontos
  7. Use the body to explain what and why vs. how
  8. Reference the issue!

Miért fontos a 8. pont?

Valójában (bizonyos szempontból) az issue behivatkozása a legfontosabb, méghozzá a visszakövethetőség (traceability) miatt.

Minden módosítás (a verziókövető rendszerben) rendelkezik egy azonosítóval, amelyhez társul, hogy ki és mikor végezte el a módosítást. Valamit egy üzenet, amely -- jó esetben -- leírja, hogy mi volt ez a módosítás. A visszakövethetőség egy adott szintig tehát szerves része a verziókövető rendszereknek.

A módosítások azonban nem csak úgy ötletszerűen történnek, hanem valamilyen feladat által meghatározott célból. Pl. jelenítsd meg a műszerfalon az autó pillanatnyi sebességét (feature), vagy javítsd ki pixel/s -> km/h átváltást, mert kerekítési hiba miatt értelmetlen érték jelenik meg (bugfix).

Ugyanakkor a feladatok (task) sem csak úgy lógnak a levegőben, jellemzően kapcsolódnak egy user story-hoz (különösen a feature-ök), de biztosan kapcsolódnak egy sprinthez (hiszen beütemezték a megoldását valamikorra), van felelősük, határidejük, stb. Úgy általában van véve egy kontextusuk. Az issue (más néven task) tartalmazza az adott feladat pontos részleteit, az issue/task trackerben akár a megoldás teljes vitafolyamata megtalálható. Pl. ki hogyan akarta implementálni, milyen érvek és ellenérvek merültek fel az egyes implementációs lehetőségek mellett/ellen, hogyan jutott a fejlesztőcsapat konszenzusra, vagy ki hagyta jóvá az adott módosítást, ki döntött arról, hogy melyik sprintbe kerüljön be, stb.

A visszakövethetőség nem csak addig a pontig érdekes és fontos, hogy ki írta át a változó típusát (pl.), hanem a teljes tervezési/döntés folyamatig visszamenőleg.

Mi van akkor ha a döntés egy face-to-face meetingen (pl. standup), skype konferenciahíváson vagy egyéb nem írásos formában történt? (A szó elszáll, írás megmarad...)

Ebben az esetben, az issue kiváló hely arra, hogy írásban is rögzítve legyenek az elhangzottak. Pl. YYYY-MM-DD-ei megbeszélés alapján az XY library segítségével fogom implementálni az analóg fordulatszámkijelzőt. Akár explicit írásos jóváhagyást is lehet kérni...

További „iskolák”

  • Az AngularJS Git Commit Message Conventions a commit üzenet fejlécét a <type>(<scope>): <subject> szabály szerint követeli meg.
    • ahol típus lehet build, ci, docs, feat, fix, perf, refactor, style vagy test
    • valójában a 1., 4. és 5. pontot ez is megköveteli; a 3.-al pont szembemegy, aminek oka, hogy a tárgy típusmegjelöléssel kezdődik, nem a tárgy szövegével
    • a tárgy és törzs sorhosszára 100 karakteres limitet ad, szemben a fenti hagyományos (akár úgy is lehet érteni, hogy elavult) terminálméretekre szabott korlátaival
  • Egy másik, az Angularéhoz nagyon hasonló a Conventional Commits
  • Ezek előnye lehet -megfelelő tooling mellett- pl. az automatizált changlelog generálás
    • nálunk nincs ilyesmire beállított eszköz

Mire jó még a commit üzenet?

Például arra is alkalmas, hogy lezárjunk vele egy issue-t. Ha a commit üzenet törzse tartalmazza a close, closes, closed, fix, fixes, fixed, resolve, resolves vagy resolved utasítások egyikét, akkor a GH automatikusan zárja az issue-t amint az a fő ágba (master) került. Pl.

Fix px/s -> km/h conversion #28

Fixes #28

Mikor commit-oljunk?

A fentiekből már látszik, hogy az egésznek akkor van értelme, ha egy-egy commit egy jól megválasztott mértékű módosítást rögzít. Az a megközelítés, hogy a munkanap végén nyomok egy commitot valami olyasféle üzenettel, hogy Changes on YYYY-MM-DD nem nagyon szolgálja a visszakövethetőséget.

Egy taszk hossza 1-4 óra (főállású fejlesztőre értelmezve), de fontos, hogy egy megszakítás nélkül elvégezhető feladat legyen. Ez azt jelenti, hogy egy taszk egyenlő egy committal? Nem. Egy taszk megoldása természetesen több commitból is állhat.

A When to make a Git Commit poszt1 alapján (is), azt mondanám, hogy akkor érdemes commitolni, ha:

  1. Befejeztem egy egységnyi munkát.
  2. Olyan módosítást végeztem, amit esetleg visszavonnék.

Az egységnyi munka módosított sorok és fájlok tekintetében rendkívül változó lehet. Egy bugfix pl. állhat egyetlen karakter módosításából, de egy refaktorálás során egy metódus átnevezése járhat tucatnyi fájl módosításával (ahol az adott metódus használva volt). Ugyanakkor a metódusátnevezés után biztosan érdemes lehet commitolni, egyéb módosítást már nem csapnék hozzá.

Ha a commit üzenetbe azt írnád, hogy Rename foobar method and fix typo in the comment #42 már biztosan két külön commitra lenne szükséged.

1

a hozzá tartozó kommenteket is érdemes átfutni

Review

A tárgy során

review process