The goal of this task is to provide final API design and code review for a library implemented by another team. To this end, you have been provided with a new repository (in the task-7 project group) containing a snapshot of another team’s repository.

The task itself 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 various aspects of the library (think of it as 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/time converter

Extend the library behavir so that it supports parsing date/time in some sensible (e.g., ISO) format and then use the extension to create a simple converter program that can be used as follows:

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

The goal of the first part is to get you to look at the library design more thoroughly. Consequently, you should first attempt to extend the library, as opposed to simply using it to extract raw strings from the command line arguments and parsing them in the application.

Note that we intentionally do not over-specify the details to allow solutions to fit the design of the library. Ideally, the library will adhere to the open-closed principle and allow extension without having to modify existing code, but the world is not ideal.

  • Depending on the library you received for review, you may be able to extend the library behavior locally (from your application) using concepts provided by the library. Usually, this would mean that you can somehow define custom option argument type with an associated parser and/or validator and allow the library to use it. This includes extending an option base class designed for inheritance, providing lambdas for parsing and/or validation, etc.
  • If the above is not possible, you should try to extend the library itself. Chances are that the library does not offer extensibility to its users, but can be reasonably extensible internally. Perhaps you just need to add a class and maybe register it somewhere and that’s it. You can then use the extension from the date converter.
  • Finally, if extending the library itself turns out to require more extensive modifications of existing code (i.e., it is not just a matter of adding a class), it is OK to fall back to just using the library to extract raw strings from the command line and processing them in the date converter.

Finally modify the CI setup so that it runs the data converter in a suitable CI stage after building the library. To integrate the date converter with the library project, check how the other example applications are integrated in the project and follow suit.

Part 2: review

The purpose of the review is to provide the library authors with written feedback on the final design and implementation of their library. You can think of it as if you were considering including the library as a long-term dependency into your project and had to justify your decision to your collaborators or supervisor.

Your feedback is not going to cost the other team any points, so you are encouraged to provide an honest opinion while keeping your tone civil. Strive to provide constructive criticism, i.e., support your opinions with examples and provide suggestions on what to improve and how. In this regard, prefer quality over quantity, i.e., focus on a few well-argued points targeting the most important issues, instead of tearing the solution apart in a flurry of details without much depth.

Also keep in mind that reviewing does not mean that you are only expected to criticize — don’t be afraid to praise where you believe it is due.

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

  • First impression (of the project)

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

    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?
    • What are the key concepts (and where can I learn more)?
    • How to use the library (short tutorial or a simple example)?
    • Which use cases can it cover (and which are beyond its scope)?
    • Can the library be extended (more complex example)?
    • How to build the library/documentation (and what is needed for that)?

    Given that this is the final version of the library, you should not have trouble getting the library to compile and finding your way around.

  • High-level review of the library API

    Summarize the basic concepts provided by the library. In this section, you should avoid discussing low-level technical details. Instead, 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 is clear what the API methods expect from the developer and how they should behave. Also find out what the library can/cannot do with respect to the task-1 requirements, i.e., how does it satisfy the functional requirements and if deviations are documented/justified.

  • Extending the library (and writing the converter application)

    Describe your approach to extending the library with support for a new value type and summarize your experience with implementing the date/time converter example.

    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 source code. Ideally, the initial page would provide a technical overview of the library and basic concepts, hyperlinked 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). In this section, you will typically discuss technical details and refer to specific classes and interfaces rather than high-level concepts.

    See the checklist below for potential questions that you can be asking yourself about the library. The list is not exhaustive and you are not required to answer all those questions in your review — the purpose of the checklist is to aid in systematic API exploration (or if you are stuck and wonder what to write about).

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 from source code)

    • 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? If not, what was missing?

  • Code style

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

Use of generative AIs

When writing the review, you may use generative AIs to improve your writing style or to express yourself better. However, you must disclose the use of AI for any purpose along with the mode of usage.

Be aware that the generative AIs tend to augment text with lots of filler words and adjectives. These may be appreciated by sales people, but tend to carry zero technical information, which goes against the purpose of the review.

You may not use generative AI to write the review for you. Also, you may not submit text that you have not written yourself to the AI (i.e., the project you are reviewing or the task specification).

Submission

To submit your solution to this task, commit both the 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 converter application should be integrated (in a reasonable way) into the library project, 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.

    Please note that submissions that fail to place the review file in the required location (or use a different name) will receive a penalty of 1 point, because handling such submissions requires manual intervention.