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
api-tests-* pattern. The branches originate at the
point of export represented by the
task-4-export tag. You will
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.
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.mdor 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.mdor, even better, think about the right content for each purpose. You can keep
README.mdrather 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
exceptionssubpackage. 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.
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.