You have been provided with a new repository containing the final library implementation from another team for final code and design review. Your task is to provide feedback to the library authors.

The actual task is (again) split into two parts. In the first part, you are expected to familiarize yourself with the library (documentation should help with the initial orientation) and develop a small extension. In the second part, you are expected to review the library as if it was a software project that you consider depending on and summarize your review in several paragraphs of coherent text (not a bullet list).

This task is done individually so that each team (including yours) receives feedback from two other students.

Part 1: date converter

You are expected to extend the library so that it supports parsing dates/times in some reasonable format and then use this extension to create a simple time-format converter program that can be used as follows:

> ./extension-program --date=2018-12-31T14:45 --format=%d.%m.
31.12.

Note that we intentionally do not over-specify the details to allow solutions to fit the design of the library. Check how the example applications are integrated in the project and follow suit. Try to extend the library in the spirit of the open-closed principle, i.e., without modifying it. In the best case, you will be able to keep the extension local to the converter application.

Finally modify the CI setup so that it runs this example program in a suitable CI stage after building the library.

Part 2: review

You should write the final review as if you were considering including the library as a long-term dependency into your project and had to justify your decision to collaborators. Your feedback is not going to cost the other team any points, so you are encouraged to provide an honest opinion. Make sure to keep the tone of the review civil. Don’t be afraid to provide praise where due — reviewing does not mean that you are only expected to criticize.

Your review should adhere to the following (rough) outline:

  • First impression

    Summarize your first impression of the library after cloning the project.

    People usually expect README.md to contain basic information about a project, so a good README.md can go a long way in setting up the user’s expectations by answering some of the potential questions up front:

    • What does the project/library do?
    • Which use cases can it cover (and which are beyond its scope)?
    • How to use the library (short tutorial or a simple example)?
    • What are the key concepts (and where can I learn more)?
    • How to build the library (and what is needed for that)?

    This is supposed to be final version of the library, so you should not have trouble getting the library to compile and find your way around.

  • Library API

    Summarize the basic concepts provided by the library. You should not (need to) discuss low-level technical details (i.e., classes) in this part, but you should discuss the API style, the responsibilities assumed by the library and those expected from the user.

    Consider common situations in which the library API is going to be used (i.e., parser definition, parsing the command line, access to parsed values, and error handling) and comment on the comfort of using the API in these situations.

    Check the API documentation to see if it clear what the API methods expect and how they behave, and find out what the library can/cannot do in the context of the task-1 requirements, i.e., how does it satisfy the functional requirements and if deviations are documented/justified.

  • Writing the converter application

    Describe your experience implementing the date converter example. What did you have to do to implement the converter and possibly extend the library with support for a new value type?

    Comment on how the concepts required to implement the converter match the concepts offered by the library. Point out what was easy (conceptual match), difficult (conceptual mismatch but workaround possible), or impossible to implement with the help of the library.

  • Documentation

    The project should provide reference documentation generated from the sourcode code. Ideally, the initial page would provide a technical overview of the library and basic concepts, hyperlink to documentation of specific classes.

    Check the contents (concept description, contracts, expected and error behavior), and coverage of the documentation for public API elements (types, methods, and method parameters).

  • Implementation

    Evaluate the quality of the implementation, readability, and coding style. This concerns mainly class responsibilities (including internal classes), use of methods for structuring code, use of variables and constants, layout of code in methods, comments. Informally evaluate test coverage, mainly to detect glaring holes in the coverage.

  • Detailed comments

    Provide detailed comments on specific issues (or highlights). See the checklist below for sample questions (not exhaustive) that can aid in systematic API exploration.

Review checklist

  • Library API

    • How does the user define parsable elements and their properties?
    • Are bounded integers, enums and strings parameter types supported?
    • Can the library generate help text based on user-provided documentation?
    • Is it possible to parse and/or validate custom parameter types and how?
    • What happens when and error (due to programmer or CLI user) occurs?
    • What is needed (information, steps) to access the parsed values?
    • Who is responsible for storing the parsed data and where?
    • Is the API declarative or imperative, stateful or stateless?
    • Does the API use mutable or immutable objects?
    • Can a user define multiple independent parsers? Is there any global state?
    • Is the API consistent? Can it be used in the wrong way?
    • Does the naming fit the problem domain?
    • Is the client code easy to read?
    • … and many others …

  • External documentation

    • What are the goals and non-goals of the library?
    • What are the key concepts provided by the library?
    • What are the key design decisions and how they reflect the library goals?

  • Reference documentation (generated)

    • Are all public classes documented?

      What is the responsibility of the class and how does it fit among the other concepts provided by the library?

    • Are all public methods documented?

      Is it clear what each method does, and how does it react to invalid data or invalid usage by the programmer, such as invalid parameter values? What constitutes valid and invalid parameter values?

    • Was the example program documented?

    • Was the documentation good enough for writing the converter or not?

  • Code style

    • Does the code follow platform conventions (naming etc.)?
    • Is the source code formatting consistent?

Submission

To submit your solution to this task, commit both the date converter application and the review to the master branch of the provided repository, and tag the final commit using the task-7-submission tag.

  • The date converter application be integrated (in a reasonable way) into the original library, ideally as a separate sub-project (similarly to other example applications).

  • The review must be a markdown document named REVIEW.md (case sensitive) placed in the .nprg043 directory, i.e., the path to the file from the project root should be .nprg043/REVIEW.md.

    Note that failure to put the review in the required location will be penalized, because such a submission needs to be handled manually.