Review

[miikka]

Background: I've been asked to review this course project. I'm not familiar with the requirements of Ohjelmistotekniikan menetelmät; these are my observations as a professional software developer assessing a new codebase.

Usability

The graphical user interface is simple and I quickly learned to use it. It seems to work in general. However, I immediately encountered a number of problems when I tried it out:

• The active tags field has no explanation. It allows the user to filter the notes by tags, but this is not obvious without trying.
• The tags field has no indication that tags are separated by space.
• When you add a new note, it is added to a non-deterministic position in the list of notes.
• There's no feedback if saving the notes fails. The command-line interface at least prints the class of the exception.
• There's no way to load the notes.
• The usual macOS text editing shortcuts such as Cmd+X for cutting do not work.

Both the graphical interface and the command-line interface have a number of low-hanging fruit improvements that I'd consider essential if you were developing a real application.

Project setup

The project is set up with modern Clojure tooling. I followed the instructions in the documentation and everything worked as I expected as an experienced Clojure developer. Only the name of the JAR file is wrong in README.

Software design

In general, the code is clear and idiomatic Clojure. The architecture is well-designed:

• There's a clean separation between the note database layer and UI layer.
• The core note database operations are implemented in purely functional style and both the in-memory state handling and file I/O operations are implemented in separately.

These make the code easy to test and change.

I have some reservations about the data model implemented in otm_notes/notes.clj. The note database consists of a note register, which is a mapping from node ids to note contents, and a tag register, which is a mapping from tags to notes.

• Because the note register is implemented with a Clojure map, it is unordered. This can be seen in the UI where adding a new note inserts the empty note in non-deterministic position in the note list.
• From database perspective, the tag register is essentially an index for the note register. It left me wondering if you measured its impact on performance: is it a necessary optimization or unnecessary complexity?

Testing

The unit tests cover the core note database operations, but not much else.

• The test coverage is good, but not excellent. There are a couple of tricky non-tested functions such as update-note that I'd like to see covered if this was a real application.
• Using property-based testing is a nice touch and the tested properties are good!
• For a real application, I'd like to see tests for saving and error handling and maybe even some UI tests. The command-line UI should be easy to test.

[codexog]

Usability

Most of the issues pertaining to the usability are resolved by reading the Manual. There is a way to load the notes, the fact that tags are space separated is mentioned explicitly. The fact that there isn't a warning in case saving fails is accurate.

Software design

It is true that the notes are added to a map which doesn't maintain any particular order. However the notes are displayed in lexicographical according to the uid in the graphical user interface, and therefore their order is in fact well defined and stable. See otm_notes/ui/jfx.