Doporučené postupy v programování – 4. úkol: Implementace, testy, dokumentace

Nezapomeňte odevzdat tento úkol do 20. 5. 2018 (přes gitlab).

Dvojice pro tento úkol jsou stejné jako pro úkol 2.

V rámci úkolu 2 jste navrhli API vaší knihovny. Tento úkol je logickým pokračováním, kdy naimplementujete požadovanou funkcionalitu. Oponentury z úkolu 3 vám pomohou v rozhodování, jestli a jak vaše API změnit, před samotnou implementací knihovny. Tento text doplňuje požadavky existujícího zadání.

Zadání

Požadavky na funkcionalitu a části řešení jsou popsány již na stránce s úkolem 2. Zde jsou pouze shrnuty jednotlivé části a upřesněny formální požadavky na odevzdání.

Řešení

Kompletní popis je tam, zde je uveden pouze souhrn.

  • Implementace
    • Splňuje funkční požadavky.
    • Přenositelnost (C++: GCC+make, C#: Mono+make, Java: Ant/make).
  • Unit testy
    • Pokrývají veřejné API co nejlépe, vnitřní API rozumně.
    • Rozumně spustitelné (nejlépe pomocí make test nebo ant test).
    • Testy jsou také kód!
  • Zdůvodnění návrhu
    • Souvislý text!
    • Délka okolo 2-3 stran A4.
    • Prostý nebo formátovaný text (.txt nebo .md).
    • Vemte v potaz přípomínky od oponentů.
  • Dokumentace
    • Zcela stačí JavaDoc (Doxygen) s rozumnou úvodní stránkou a vhodně provázaný odkazy (alespoň mezi hlavními třídami).
    • Buď ji zahrňte do projektu nebo napište postup vygenerování, pokud není příliš složitý (tj. ant javadoc je ok).

Unit testy

Unit testy by měly testovat všechny veřejné třídy a metody, které tvoří programátorské rozhraní knihovny. Snažte se je psát tak, jako byste byli testeři v rámci většího týmu a dostali jste za úkol pomocí unit testů ověřit kvalitu kódu, který napsal váš kolega a za toto ověření byste byli odpovědní (případné ponechané bugy by byly váš problém). Zaměřte se na soulad s dokumentací, dodržování kontraktů, různé okrajové podmínky, korektnost ošetření chybových stavů (např. špatných hodnot parametrů) atd.

Nezapomeňte, že kód testů je kód jako každý jiný, takže kód testů pište přehledně, strukturovaně, s vhodně volenými názvy tříd, metod, proměnných, atd. Specificky u testů je důležité, aby bylo na první pohled vidět, že test je správně.

Pro psaní unit testů použijte libovolný testovací framework určený pro daný jazyk. Výsledné testy by měly být integrované s daným řešením úkolu a měly by jít snadno spustit. V případně, že v implementaci knihovny narazíte na chyby, testy pochopitelně neproběhnou na 100%, ale skončí s výpisem chyb.

K testům není nutné psát podrobnou programátorskou dokumentaci jako v případě řešení, připojte pouze stručný návod jak testy spustit a jak by měly vypadat jejich výsledky. Opět nezapomeňte, že testy jsou také kód a jako takový zasluhuje slušné komentáře.

Odevzdání

Úkol odevzdejte přes gitlab jako poslední commit před deadline. Zdůvodnění návrhu nazvěte Overview.txt nebo Overview.md

Hodnocení

Na řešení bude hodnoceno především následující:

  • Implementace
    • Kvalita návrhu.
    • Kvalita kódu (názvy, komentáře, odpovědnost tříd, ...)
  • Unit testy
    • Pokrytí kódu.
    • Volba vhodných testovacích případů.
    • Organizace a srozumitelnost testů.
  • Zdůvodnění návrhu
    • Srozumitelnost.
  • Dokumentace
    • Provázanost.
    • Srozumitelnost.

Přesná bodová stupnice není stanovena; obecně lze říct, že budou strhávány body za "prohřešky" ve výše uvedených kategoriích.

Navazující úkol bude opět typu „oponentura“, nezapomeňte si proto pohlídat anonymitu zdrojového kódu.

Opoždění odevzdání budeme penalizovat ztrátou 7 bodů za každý den.

Důvodem je opět návaznost jednotlivých úloh, kdy neodevzdaná řešení blokují práci i ostatním studentům.

Recommended Programming Practices – 4th assignment: Implementation, tests, documentation

Do not forget to submit this assignment until 20. 5. 2018 (into gitlab).

The pairs for this assignment are the same as for the assignment 2.

You have designed an API of your library in the assignment 2. This assignment is a logical continuation, in which you will implement required functionality. Reviews from the assignment 3 will help you to decide whether and how to change your API before implementing it. This text extends the requirements of the existing assignment.

Assignment

The functional requirements and parts of the solution are already described in assignment 2. Here are only summarized individual parts and concretized formal requirements for the submission.

Solution

Full description is there, here is only a summary.

  • Implementation
    • Satisfies functional requirements.
    • Portability (C++: GCC+make, C#: Mono+make, Java: Ant/make).
  • Unit tests
    • Covers public API as much as posible, covers private API reasonably.
    • Reasonably executable (best using make test or ant test).
    • Tests are code as well!
  • Justification of the design
    • Coherent text!
    • Length around 2-3 A4 pages.
    • Plain or formated text (.txt or .md).
    • Take into account evaluation from your peers.
  • Documentation
    • Sufficient is JavaDoc (Doxygen) with reasonable main page with suitably linked sections (at least between main classes.
    • Either include it into your project or write down the steps to generate it, if the procedure is not too complicated (i.e. ant javadoc is ok).

Unit tests

All public classes and methods that form the API of the library should be covered by unit tests. Write them as if you were a tester in a larger team and your task is to verify code quality of your colleague using the unit tests and as if you were responsible for any undetected bugs. Focus on the compliance with documentation, abidance of contracts, boundary conditions, correctness of managing error states (e.g. bad parameter values) etc.

Do not forget that tests are code as any other, therefor write the code clearly, structured, with suitable names for classes, methods, variables, etc. It is important specifically for tests that it can be easily seen that a test are correct.

Use arbitrary testing framework designated for your language of choice to write the unit tests. The unit tests should be integrated with your solution and should be easily executable. If there are bugs in the library the tests will obviously not pass for 100%, rather they end with report of errors.

It is not necessary to write detailed program documentation for the tests as it is for the library code, include only brief instructions how to execute the tests and how the results should look. Again, do not forget that tests are code as any other and as such it deserves proper comments.

Submission

The assignment will be submitted via gitlab as the last commit before deadline. Justification of your design should be named Overview.txt or Overview.md

Evaluation

There will be evaluated especially the following:

  • Implementation
    • Design quality.
    • Code quality (names, comments, responsibility of classes, ...)
  • Unit tests
    • Code coverage.
    • Choice of adequate test cases.
    • Organization and clarity of tests.
  • Design justification
    • Clarity.
  • Documentation
    • Interconnection.
    • Clarity.

The exact scale for points is not established; generally the points will be removed for "violations"; in the categories above.

The follow up assignment is again a "review" type, therefore do not forget to keep your code and text anonymous.

Late submission will be penalized by 7 points for each day of delay.

The reason for that is again the continuity of assignments, where late submission are blocking the work of other students.

Logo of Faculty of Mathematics and Physics
  • Phone: +420 951 554 267, +420 951 554 236
  • Email: info<at-sign>d3s.mff.cuni.cz
  •  
  • How to find us?
Modified on 2018-04-24