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).

API tests

The API test from other students haven been pushed to the api-testing branch of your project. You will find them in the incoming directory, one subdirectory for each submission. You should integrate these tests into your project and delete both the incoming directory and the api-testing branch when you are done.

When integrating the tests into your project, try to keep them in a separate source directory, but do run them together with your own 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.
    • Typically found in README.md (it is very disappointing to find it empty)
  • 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.
  • 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.