Úkol 5: Extension

Obecně

Zadání

Řešení

Testy

Odevzdání

Hodnocení

Generally

Assignment

Solution

Tests

Submission

Evaluation

Stránky předmětu

Doporučené postupy v programování – 5. úkol: Hodnocení, rozšíření

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

Dvojice pro tento úkol zůstávají stejné.

Vaším posledním úkolem bude zhodnotit knihovnu implementovanou vašimi kolegy a rozšířit její funkcionalitu. Knihovnu, která vám poslouží jako zadání, najdete v gitlabu jako nový projekt, do kterého dastanete přístup.

Zadání úkolu

Zorientujte se v kódu knihovny, která vám byla přidělena. V tomto by vám mělo pomoci zdůvodnění návrhu. Ve vašem review nejprve zhodnoťte již zmíněné zdůvodnění návrhu, nezapomeňte poznamenat, jestli vám tento dokument usnadnil práci a případně jak. Poté rozeberte kvalitu a styl kódu, funkcionalitu, zda knihovna splňuje zadání, její pokrytí testy a snadnost nebo obtížnost jejího používání. Také zhodnoťte, jak snadné nebo těžké bylo knihovnu rozšířit, tj. jak byla knihovna připravena na budoucí rozšíření. Review píše každý sám za sebe.

Knihovnu rozšiřte tak, aby bylo možné v ini souboru použít direktivu #include <file>. Includování souboru je ekvivalentní vložení celého obsahu includovaného souboru do souboru s includem. V jednom souboru může být includováno libovolné množství jiných souborů. Dejte si také pozor na to, že includování je rekurzivní, tzn. includování souboru, který sám obsahuje include musí také fungovat.

Další rozšíření se týká podpory nových datových typů. Knihovna by měla podporovat volby typu datum a locale (alespoň v podobě, kterou podporují knihovny vámi zvoleného jazyka), může přidat i další typy, které vás napadnou.

Řešení

• Hodnocení
  • Souvislý text!
  • Délka okolo 2-3 stran A4.
  • Formát markdown (.md).
• Implementace rozšíření
  • Splňuje funkční požadavky.
  • Přenositelnost (C++: GCC+make, C#: Mono+make, Java: Ant/make).
• Unit testy
  • Měly by pokrývat kód vašeho rozšíření.
  • Pokud zadaná knihovna nebyla plně pokryta testy, měli byste doplnit i ty.
  • Rozumně spustitelné (nejlépe pomocí make test nebo ant test).
  • Testy jsou také kód!
• Dokumentace
  • Zcela stačí JavaDoc (Doxygen) s rozumnou úvodní stránkou a vhodně provázaný odkazy (alespoň mezi hlavními třídami).
  • Může být rovnou v repozitáři 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 bude odevzdán jako poslední commit před deadline v gitlabu. Hodnocení knihovny nazvěte review_<nr>.md. Např. student2 vytvoří review_2.md

Hodnocení

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

• Hodnocení
  • Srozumitelnost.
• 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ů.
• 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.

Za hodnocení můžete získat až 10 bodů. Za rozšíření můžete získat až 10 bodů.

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

Recommended Programming Practices – 5th assignment: Review, extension

Do not forget to submit this assignment until 3. 6. 2018 (into gitlab).

The pairs for this assignment remain the same.

Your last task will be to review a library implemented by your colleagues and to extend its functionality. You can find the library that will be your starting point in gitlab as a new project that you will be granted access to.

Assignment

Get familiar with the code of the given library. The Overview.md should help you with orientation in the project. In your review evaluate firstly the Overview.md, don't forget to mention whether it was helpful and eventually how. Then focus on the quality and style of the code, functionality, whether the library satisfy the formal requirements, test coverage, and ease or difficulty of using the library. Evaluate also, how easy or difficult it was to extend the library, i.e. how was the library prepared for future extension. The review is not done in pairs, everyone creates his/hers own.

Extend the library so it is possible to use #include <file> directive in the ini file. Inclusion of a file is equivalent to inserting the whole file into the file with the #include. In one file it is possible to include an arbitrary number of other files. Be also careful about that inclusion is recursive, i.e. inclusion of a file that also contains #include has to work as well.

Next extension is about new data types. The library has to support options with type date and locale (at least into an extend supported by the libraries of your programming language), you can also add another data types that you can think of.

Solution

• Review
  • Coherent text!
  • About 2-3 A4 pages.
  • Markdown format (.md).
• Extension implementation
  • Satisfies functional requirements.
  • Portability (C++: GCC+make, C#: Mono+make, Java: Ant/make).
• Unit tests
  • They should cover the extension code.
  • If the library was not fully covered by tests, you should also add those.
  • Easy to launch (best with make test or ant test).
  • Tests are code as any other!
• Documentation
  • JavaDoc (Doxygen) is sufficient with reasonable main page and with convenient links (at least between main classes).
  • It can be directly in the repository or provide the steps needed to generate it, if that is easy enough (i.e. ant javadoc is OK).

Unit tests

All public classes and methods, which make the API of the library, should be covered by unit tests. Write them as if you were testers in bigger team and your task is to ensure code quality with your tests and as if you were responsible for any bugs left. Focus on the compliance with documentation, contracts, different corner cases, correctness of handling error states (e.g. wrong parameter values) etc.

Do not forget that tests are code as any other, therefor write the code of tests clearly, structured, with suitable names for classes, methods, variables, etc. Specifically for tests it is important to see, that the test is correct, on the first sight.

Use any test framework for your language to write the tests. Resulting tests should be integrated with the assignment solution, and they should be launched easily. In case you run into mistakes in the library implementation, the tests reasonably won't succeed on 100% but they will end with error message.

It is not necessary to provide detailed program documentation for the tests as you will for the library, it is sufficient to provide only brief instructions how to run the tests and how the results should look. Again, don't forget that tests are also a code and as such it deserves decent comments.

Submission

The assignments will be submitted as a last commit before the deadline in gitlab. Name the review of the library as review_<nr>.md. For example student2 will create review_2.md

Evaluation

On your solution there will be evaluated the following:

• Review
  • Clarity.
• Implementation
  • Design quality.
  • Code quality (names, comments, responsibility of classes, ...)
• Unit tests
  • Code coverage.
  • Selection of suitable test cases.
  • Organization and clarity of the tests.
• Documentation
  • Interconnection.
  • Clarity.

There is no exact scale for points; generally the points will be taken for "sins" against concepts in the categories described above.

For the review you can get up to 10 points. For the extension you can get up to 10 points.

Late submission will be penalized by 3 points for each day.

Modified on 2018-05-23