After receiving feedback and API tests from your colleagues, your task is now to finish the implementation of your library while adhering to design and coding guidelines presented during lectures. In the second half in the implementation period, you will have to give a short presentation on the progress of your implementation (which is officially task #6).

Integrating API tests

The API tests from your colleagues been pushed to separate branches matching the api-tests-* pattern. The branches originate at the point of export represented by the task-4-export tag. You will find a diffstat output for each set of tests (or a note indicating a missing test suite) in the .nprg043/tests directory. You should merge the branches into your project (and delete them afterwards).

When integrating the tests into your project, keep them in separate source directories, but do run them together with your own (unit) tests.

Implementation checklist

When finalizing the implementation, please pay attention to the following checklist which emphasizes some of the things that are typically checked during the final review (both by students and the course instructor):

  • Overview documentation
    • Provides high-level overview of the project and key concepts, and shows basic examples corresponding to common use cases, so that a potential user can get started quickly.
    • Lists project dependencies a links to additional resources (such as reference documentation).
    • If you refer to classes, you should provide specific links to the reference documentation.
    • Typically found in README.md (it is very disappointing if there is no README.md or if it is (almost) empty – treat it as something that conveys the first impression of your project).
  • Reference documentation
    • Provides detailed description of the public API and documents the most important design decisions with respect to typical use cases. The idea is that a user should be able to understand the logic behind your design.
    • When mentioning specific classes, it is good idea to link to their reference documentation.
    • Each public method should have a reasonable description (reasonable description is not a name of the method with added spaces in between words).
    • Be meticulous in describing aspects of the contract provided by the method and the range of values accepted by the parameters.
    • If your library is extensible, describe the extension mechanism and its intended use, ideally with an example.
    • The refence documentation is typically generated from source code and you should make this process as simple as possible (one touch). If the process of generating documentation is too involved, do provide a pre-generated archive in your submission.
    • The title page of the generated documentation should not be empty. Think about reusing the contents of README.md or, even better, think about the right content for each purpose. You can keep README.md rather simple and point to the reference documentation to avoid duplicating content.
  • Code formatting and organization
    • Pick a style and stick to it, consistently, throughout the whole project.
    • Use white space to separate logical blocks of code within classes and within methods.
    • Use white space around operators (unless they are unary) and around keywords. Think of the code as prose, where you need to be able to easily distinguish words and paragraphs.
    • Strive for self-documenting code (lets you document private parts of your code less verbose). Key aspects of self-documenting code are good names for values and behavior, i.e., variables, fields, and methods.
    • Use private methods extensively to break code up into smaller (named) blocks that you use to compose more complex behavior in higher-level methods. If you see a block of code with a comment, consider turning it into a private method that you call.
    • Strive to make data flow between methods explicit. This typically means to avoid accessing data in “global” manner. In broader sense, this also applies to accessing instance data (fields) from private methods deep in the call chain. It is usually better to pass the data into worker functions from higher-level functions.
    • Keep related things together and use scoping diligently to avoid making your internal APIs visible to the user. Common mistake is to use packages to organize source code, e.g., putting exceptions into exceptions subpackage. To make effective use of package-private scoping (or similar concept in non-Java languages), you should only have one package for one unit of reuse. This will allow you to only expose API classes and keep a lid on the rest.
  • Build system, one-touch testing, and CI
    • Your code must be automation-friendly, which means it must be possible to compile without an IDE, even if you use IDE extensively.
    • Code in our master branch (the one you will be submitting) should always compile and require only a single command to run tests.
    • Keep a CI configuration so that each new commit can be automatically tested.

Please keep in mind that the list is far from exhaustive and that you should generally try to stick to the various guidelines presented during lectures, unless there is a good and documented reason for not doing so.

Submission

When you are satisfied with your solution, make sure it is in the master branch of your task-1 repository and tag the commit using the task-5-submission tag. The code will be then exported for final review.