CS2113T Project: DiveLog

Overview

DiveLog is a desktop application that mainly uses CLI as a user interface. Dive Log provides a simple way for underwater divers to input details of their dives such as the time they spent at a particular depth, and the application will keep track of their nitrogen levels. This allows divers to plan their next trip safely.

Dive Log is able to calculate accurately the diver’s current Blood Nitrogen Composition, which is used to evaluate when it will be safe to dive again, and for how long.

Dive Log is based on Addressbook level 4 and is developed as part of CS2113T project requirements.

Summary of contributions

  • Code Contributed [Cjunx]

  • Major enhancement: Implemented a Planning Mode

    • What it does: This feature allows users to be able to plan for future dives without the fear of corrupting their current data. When the users exit planning mode, the data is restored to before when entered planning mode. If the user wants to transfer planning data to normal mode, the user can use the portover command.

    • Justification: This is a major feature of the app as divers often want to plan their dives ahead of their trips. This also helps to prevent the instance where divers cannot board a plane ride due to too high of a Nitrogen composition in the body. <Reference>

    • Highlights: This enhancement works across the different commands and will require understanding of every command class file in order to properly implement.

  • Minor enhancement: Created Time, OurDate parameters in a DiveSession and improved helper class CompareUtils and parserUtil which contain methods to handle OurDate and Time. The two parameters are crucial in logging a dive, and methods in CompareUtils are also crucial in calculations of Pressure Groups which is the main feature of our app. CompareUtils contain methods that are used to help calculate Pressure Group.

  • Other contributions:

    • Enhancements to existing features:

      • Wrote tests for helper method to ensure adequate code coverage (Pull requests #58, #154)

    • Documentation:

      • [UG] Introduced tables to organise information (Cosmetics) #3

      • [UG] Tweaked the whole User Guide’s tone to a more interactive and friendly guide #66 #135

      • [UG] Documented new commands/features #39

      • [DG] Added components pertaining to Sorting, Planning Mode & New parameters in a Dive: #41 #139 #146

    • Community:

      • PRs reviewed (examples: #47)

      • Suggestions & discussions through comments on Issue trackers (examples: #17)

Contributions to the User Guide

Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

Setting parameters to sort dives : sortby [coming in V2.0]

In V1.4, all dives are sorted automatically according to time and date by default.

Want to view your dives in ranked order by different options? Simply type sortby followed by a KEYWORD, your following list, find commands will return you all your dive sessions in that particular order.

Format: sortby KEYWORD WARNING: You can only use the specific keywords below.

Table 1. Table of parameters available to sort by
Parameter Type Keyword

Time

time

Location (lexicographical)

location

Duration of Dive

duration

Planning Mode : newplan or normalmode

The planning mode is a temporary space for you to plan trips and to simulate dives. This is especially important if you are planning on a multiple day diving trip!
When you enter the planning mode, simply enter simulation dives as per how you would use the other commands normally.

When you exit, all your simulation files will be deleted automatically. In the Current V1.4, planning mode only supports add, delete and edit commands

Format: newplan to enter Planning Mode, normalmode to exit planning mode.

When you exit the planning mode, you will return to the state before you entered.

Port files from Planning Mode to normal mode : portover

When you have finished your plan and found the perfect set of dives, simply input the portover command and the app will port all planning data into data in the normal mode.

You cannot use this command in normalmode as there are no planning data to port over.

Contributions to the Developer Guide

Given below are sections I contributed to the Developer Guide. They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

New Parameters & conditions in a DiveSession

Timezone

Considering that users would dive in many different parts of the world, we have taken the effort to implement a Timezone parameter to ease users in adding new dives into the Dive Log without the need to convert any time to Local time.
We have decided to utilise the format of UTC, given its universal usage around the world. The UTC timezones range from -12 to +12, including 0. Singapore lies in the timezone of UTC+8.

  • Alternative 1 (current choice): When calculating Pressure Groups using TimeZone, all time is converted to UTC time before calculating duration, and subsequently pressure groups and its resultant results.

    • Pros: There is no confusion of timezones when doing complex calculations.

    • Cons: There is a need to convert time from UTC time back to local time. If not taken care of, inaccurate times may be shown.

  • Alternative 2: Adopt Java SE 9’s java.time library

    • Pros: There are pre-built algorithms and methods in the library.

    • Cons: Takes time to learn and to adopt the methods, which might not be efficient for our light usage.

Time and OurDate

Time and OurDate are 2 of the new parameters in the Dive Log. In order to be able to calculate the Pressure Groups automatically, there has to be a time and date parameter. We have decided to create our own class.

  • Alternative 1 (current choice): Use a 4 length String to contain time and 8 length String to contain date.

    • Pros: When reading in data from the ArgumentMultimap, it requires very little effort in parsing. Also, the use of String allows for versatile typecasting into long, int, or Java SE 7’s SimpleDateFormat. Similarly, the use of String and long as main type allows for better versatility among different methods.

    • Cons: Data needs to be parsed into Java SE 8’s java.date and Java SE 7’s SimpleDateFormat in order to calculate time differences. This means that there can potentially be many type conflicts. However, this problem is contained in a helper class CompareUtils which handles methods like checkTimeDifference (returns the difference between 2 given time and date), getLocalDate(gets the local date and time), convertTimeToUtc(converts given date into UTC timing) and convertTimeToLocal(converts a date into Local time and date).

  • Alternative 2: Adopt Java SE 9’s java.time library

    • Pros: More volatile as the library contains many ready-made solutions. Also, java.time also allows for the easy implementation of local time, which is one of our improvements made to AB4.

    • Cons: Takes time to learn and to adopt the methods, which might not be efficient for our light usage. Also, it will only be compatible with Java SE 9.

Sorting of data

We have considered that once a user has a considerable number of dives registered in the app, the user would potentially have difficulty finding dives, even with the find function. (as many dives can have the same parameters such as location) To simplify the app usage, this command allows for users to decide the way that the data shown to them is organised.

Design Considerations

  • Current implementation: A sort method with a time/date comparator is called every time a new dive is added, deleted or edited.

  • Potential improvement to the feature 1: Add a sortby CLI command, which decides how to sort the data by. Potential additional methods are sorting by Name (alphabetical) or Duration of Dive.

    • Method to implement:
      Step 1: Create a new Command with a Command Parser that reads in the Command Prefix and a [KEYWORD], which will dictate the parameter to sort by. The Command and Parser file should look like below:

sortbyparser
Figure 1. Command Parser File Sample
sortbyclass
Figure 2. Command Class File Sample

Optional: Create a enum with the parameters you want to sort the data by (E.g Time, Location and Duration)

Sample Enum
public enum SortCategory {
TIME, LOCATION, DURATION
}

Step 2: Create a sort method preferably in a separate utils class. This method should take in the parameter to sort by. (It will be easier and less prone to mistakes if Step 2 was used) The corresponding comparators should be created. The sort method should look something like b

sortmethod
Figure 3. Sort method Sample

Step 3: Ensure that the divelog refreshes / reflects the newly sorted. You can do this by calling for the sort method after every add or edit command. You can also create a new event in commons.events.

  • Pros: Once implemented, to increase the number of parameters / methods to sort the data by, simply create a new corresponding comparator, add the respective prefixes the parse for, and to increase the number of parameters included in the Enum file.

  • Cons: Can be troublesome to implement in the beginning.

Potential improvement to the feature 2: Reverse the current order by calling reverseorder

  • Method to implement: Simply reverse the comparator in the sorting methods, where comparators are stored in a sample method shown in Figure 12. (above)

  • Pros: Improved usability and thus better UX.

  • Cons: Increased difficulty to maintain as the

New Feature: Planning Mode (with portover capability)

From our verbal surveys with test users and from our user stories, we have decided to implement a Planning mode in order for users to plan their dives ahead of their trips safely without worrying about corrupting their current data. Below shows the activity diagram of the planning mode.

planningAD
Figure 4. Activity Diagram for planning mode

Design Considerations

  • Alternative 1 (current choice): When in planning mode, a counter increments every time a command is called. In addition, there is now a state called planning mode, which shows true if in planning mode and false if in normal mode.

    • When the user chooses to exit and enter normalmode, the underlying method calls for a undo method and decreases the counter. This will repeat until the counter is zero, whereby then the state of the machine will change back to normal mode.

    • If the user decides to call portover, the counter is simply reset to 0 and the state of the machine is changed back to normal mode.

    • Pros: Uses a method that is already present, undo. This means there won’t be two implementations of the same method.

    • Cons: The limitations of this method lie in its sole ability to handle add, delete and edit commands in planning mode. Any other commands are not accepted.

  • Alternative 2: Create a temporary Stack to store commands instead of just a counter. The stack is created when user enters planning mode, and is destroyed after exiting planning mode.

    • Pros: All types of commands can now be used in planning mode, and not just add, delete and edit

    • Cons: Extra implementations and considerations have to be taken into account. This might increase coupling between classes.