write program profile for assignment 1

1 files changed, 210 insertions, 5 deletions

diff --git a/src/Q1/README.md b/src/Q1/README.md
index a7065a5..3b73401 100644
--- a/src/Q1/README.md
+++ b/src/Q1/README.md
@@ -31,17 +31,222 @@ and incorrect inputs (e.g., phone number containing special characters).
 
 2. Description of the Code: 
 
-[Briefly describe how you solved the problem in your code. You should include short description of classes, methods, and variables (if necessary) that you used in your code.]
+I solved this exercise by installing `maven` and `junit`. Then I started
+implementing the `AddressBook` API one method at a time.
+
+I had trouble understanding the `compareNames` API because it was
+non-intuitive to me. I have previously worked with `C#` and am familiar
+with the `IComparer<T>` interface so I looked for the equivalent in
+Java. I found the `Comparable<T>` interface and chose to implement that.
+
+The `Comparable<T>` interface requires implementers to implement a
+method named `compareTo` that returns an integer value. This interface
+is used for sorting.
+
+Instead of trying to interpret how the `compareNames` method is supposed
+to behave, I chose to delegate to `compareTo` and return the string
+representation of the integer value.
+
+I also chose to override equality for this object to use `value`
+equality instead of `reference` equality.
+
+For code style I chose to use the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). I used a maven plugin to auto format the code to abide by the style guide each time I ran the tests.
 
 3. Errors and Warnings:
 
-[Please enlist your Errors and Warnings (maximum five) that you encountered in your code and how you solved them. An example of this is shown in Table 1.]
-Table 1: List of Errors and Warnings Encountered in the Program
+I practice test driven development. So I always focus on writing a
+failing test first. This allows me to make sure that I see the intended
+failure in my test before implementing the required code to make it
+pass. It also helps me design the API of my software from the
+perspective of the client code that would use my software. The design
+benefits of test driven development were not as useful here, since the
+design of the API was provided to us in the assignment.
+
+Here's an example of a failure that occurred when I wrote the test first
+before implementing the required interface.
+
+```bash
+モ mvn test
+[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
+[INFO] skip non existing resourceDirectory /Users/mokha/development/gh/comp-268/src/main/resources
+[INFO]
+[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ assignment1 ---
+[INFO] Changes detected - recompiling the module!
+[WARNING] File encoding has not been set, using platform encoding UTF-8, i.e. build is platform dependent!
+[INFO] Compiling 24 source files to /Users/mokha/development/gh/comp-268/target/classes
+[INFO] -------------------------------------------------------------
+[ERROR] COMPILATION ERROR :
+[INFO] -------------------------------------------------------------
+[ERROR] /Users/mokha/development/gh/comp-268/src/Q1/AddressBookTest.java:[21,12] cannot find symbol
+  symbol:   method setFirstName(java.lang.String)
+  location: variable subject of type Q1.AddressBook
+[ERROR] /Users/mokha/development/gh/comp-268/src/Q1/AddressBookTest.java:[81,9] cannot find symbol
+  symbol:   method setFirstName(java.lang.String)
+  location: variable hunk of type Q1.AddressBook
+[ERROR] /Users/mokha/development/gh/comp-268/src/Q1/AddressBookTest.java:[85,10] cannot find symbol
+  symbol:   method setFirstName(java.lang.String)
+  location: variable shiro of type Q1.AddressBook
+[INFO] 3 errors
+[INFO] -------------------------------------------------------------
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD FAILURE
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time:  2.853 s
+[INFO] Finished at: 2019-05-11T21:26:49-06:00
+[INFO] ------------------------------------------------------------------------
+[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.1:compile (default-compile) on project assignment1: Compilation failure: Compilation failure:
+[ERROR] /Users/mokha/development/gh/comp-268/src/Q1/AddressBookTest.java:[21,12] cannot find symbol
+[ERROR]   symbol:   method setFirstName(java.lang.String)
+[ERROR]   location: variable subject of type Q1.AddressBook
+[ERROR] /Users/mokha/development/gh/comp-268/src/Q1/AddressBookTest.java:[81,9] cannot find symbol
+[ERROR]   symbol:   method setFirstName(java.lang.String)
+[ERROR]   location: variable hunk of type Q1.AddressBook
+[ERROR] /Users/mokha/development/gh/comp-268/src/Q1/AddressBookTest.java:[85,10] cannot find symbol
+[ERROR]   symbol:   method setFirstName(java.lang.String)
+[ERROR]   location: variable shiro of type Q1.AddressBook
+[ERROR] -> [Help 1]
+[ERROR]
+[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
+[ERROR] Re-run Maven using the -X switch to enable full debug logging.
+[ERROR]
+[ERROR] For more information about the errors and possible solutions, please read the following articles:
+[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException
+```
+
+Here is the output after fixing the failing test:
+
+```bash
+モ mvn test
+[INFO] Scanning for projects...
+[INFO]
+[INFO] -------------------< ca.mokhan.comp268:assignment1 >--------------------
+[INFO] Building assignment1 1.0-SNAPSHOT
+[INFO] --------------------------------[ jar ]---------------------------------
+[INFO]
+[INFO] --- fmt-maven-plugin:2.8:format (default) @ assignment1 ---
+[INFO] Processed 48 files (0 reformatted).
+[INFO]
+[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ assignment1 ---
+[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
+[INFO] skip non existing resourceDirectory /Users/mokha/development/gh/comp-268/src/main/resources
+[INFO]
+[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ assignment1 ---
+[INFO] Changes detected - recompiling the module!
+[WARNING] File encoding has not been set, using platform encoding UTF-8, i.e. build is platform dependent!
+[INFO] Compiling 24 source files to /Users/mokha/development/gh/comp-268/target/classes
+[INFO]
+[INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ assignment1 ---
+[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
+[INFO] skip non existing resourceDirectory /Users/mokha/development/gh/comp-268/src/test/resources
+[INFO]
+[INFO] --- maven-compiler-plugin:3.1:testCompile (default-testCompile) @ assignment1 ---
+[INFO] Changes detected - recompiling the module!
+[WARNING] File encoding has not been set, using platform encoding UTF-8, i.e. build is platform dependent!
+[INFO] Compiling 24 source files to /Users/mokha/development/gh/comp-268/target/test-classes
+[INFO]
+[INFO] --- maven-surefire-plugin:2.12.4:test (default-test) @ assignment1 ---
+[INFO] Surefire report directory: /Users/mokha/development/gh/comp-268/target/surefire-reports
+
+-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running ca.mokhan.comp268.AppTest
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.006 sec
+Running ca.mokhan.test.CandidateTest
+Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.051 sec
+Running ca.mokhan.test.NumberTest
+Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.019 sec
+Running ca.mokhan.test.EmployeeSavingsTest
+Tests run: 6, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.006 sec
+Running ca.mokhan.test.CartesianCoordinateSystemTest
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0 sec
+Running ca.mokhan.test.CommunicationTest
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0 sec
+Running ca.mokhan.test.TaxReturnTest
+Tests run: 11, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.001 sec
+Running ca.mokhan.test.BanffMarathonRunnerTest
+Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0 sec
+Running ca.mokhan.test.AddressBookTest
+Tests run: 12, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.001 sec
+Running ca.mokhan.test.TriangleTest
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0 sec
+Running ca.mokhan.test.BonusOnSavingsTest
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0 sec
+Running ca.mokhan.test.HailstoneSequenceTest
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0 sec
+
+Results :
+
+Tests run: 51, Failures: 0, Errors: 0, Skipped: 0
 
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time:  2.885 s
+[INFO] Finished at: 2019-05-11T21:28:34-06:00
+[INFO] ------------------------------------------------------------------------
+```
 
 4. Sample Input and Output:
-[Provide some test cases with sample input and output of your program.]
+
+The test cases are described in `AddressBookTest.java`.
 
 5. Discussion:
 
-[In this section, you may include some discussion about the debugging strategy that you used, e.g., searched the Web for a solution, contacted tutor, solved by self, used a debugging tool, posted in forum, talked to a friend, etc.]
+When I look at the design for the `AddressBook` class there are a few
+things that come to mind.
+
+1. The name `AddressBook` is a poor choice for a name. This object does
+   not represent an address book but rather a single contact in an
+   address book. I would split this class into two. One class named
+   `Contact` that represents the individual details for a contact in the
+   address book and a class named `AddressBook` that acts as the
+   aggregate root for contacts.
+2. This is more of a comment on Java than the API design, but `Java`
+   properties seem to requires A LOT of ceremony.
+
+For example in `Ruby` you can define a property/attribute very
+succinctly.
+
+```ruby
+class Contact
+  attr_accessor :first_name
+end
+```
+
+C# also has a nice shorthand for this. C# also allows specifying
+different access control for the getter and setter.
+
+```csharp
+public class Contact {
+  public string FirstName { get; set; }
+}
+```
+
+Finally the `Java` version requires much more ceremony.
+
+```java
+public class Contact {
+  private String firstName;
+
+  public String getFirstName() {
+    return this.firstName;
+  }
+
+  public void setFirstName(String firstName) {
+    this.firstName = firstName;
+  }
+}
+```
+
+3. Documentation. This is pet peeve of mine. Writing metadata style
+   comments to describe the API of a component makes sense when you are
+   building shared libraries that you intend to distribute. My preferred
+   style of documentation for any other code is executable
+   documentation. Executable documentation is the kind of documentation
+   that stays up to date with the code. It is very easy for code
+   comments to go stale and not match the actual behaviour of the code
+   as the system changes. However, executable documentation cannot go
+   stale because then it will fail to generate. Executable documentation
+   is more commonly known as test automation. 
+   .i.e Functional, Acceptance, Integration, Unit tests etc.