MyISERN 2.0 Review

The code I reviewed is from team yellow.

1. Installation
I can download the distribution file without any problem. I also unzipped it with ease because I used the WinRAR, but my other team member had problem unzipping it while using the default window unzipper.

Since there is no installation guide, I followed the developer guide and tried to build the system. Since team yellow is using a whole new system, there is no easy runnable war file. I downloaded XAMPP and Symfony as the guide told me to. When I tried to install the XAMPP, I had problem of getting the Apache server running. However, my other team member do not have that problem. After googling several pages, I discovered that this is quite a common problem, and there are many ways to "tweak" around it. I use the word "tweak" because none of them seem to guarantee to fix the problem. I finally got the XAMPP homepage show up on my localhost after I turned off my firewall and stopped some of my IIS services, which I have no clue what those services are used for.

However, my journey is pretty much ended here. I tried to install the Symfony framework, which is a lot harder than the XAMPP. The link provided in team yellow's guide does not give any useful information and it is more suited for unix users. The "pear" command-line thing seems come up from nowhere. I searched inside the folders from XAMPP and Symfony, and I did find some things called "PEAR", I tried every single execuatable, but they did not give me any luck. I tried to refer to the guide from team lime, which is using the same framework, but team lime is using WAMP, which is something different from XAMPP, and thus did not go too well either.

My other team members are pretty much stuck as I do. I finally had to give up after like two hours of searching the internet and reading relevent materials. Although Edward is managed to get the Symfony working at the end, he did not get the web app running still.

2. Code format and conventions
I have no experience for programming in PHP, therefore I do not know how well-formatted the code is. I remember team yellow mentioned a PHP eqivalence of checkstyle in their demo, but due to the reason I couldn't get the system running, and there is no guideline on how to run the tool, I have no clue to test it out.

3. Test case
Black box perspective: Since the system is not built, I cannot evaluate this.
White box perspective: Same reason as above.
Break da buggah: Same reason as above.

4. User interface
Although I am not able to build the system, I am able to see part of the website in my browser from those PHP files. The interface is very clear, and I like the coloring of the table cells which makes the whole page pretty neat. However, since these are partially of the interface, I cannot really evaluate it.

5. Three Prime Directives

Since the program cannot be built, it does not accomplish a useful task. As an external user, I am not able to install and use the system. As an external developer, I am not able to enhance the system easily, maybe I could get it working after putting considerable amount of effort into it.

6. Summary and lesson learned
From this review, I once again realized how important the documentation can be to a system. I had terrible experience working with software that has bad documentations. I do admire the courage of team yellow to take on a brand new system. Here is one suggestion I have: create a detailed installation guides with A LOT of pictures in it, you can safely assume the users have no knowledge of any tools you have used here, which is probably true for most of the class. Do not refer to any other online guides, they might not suit your system the best.

MyISERN 1.3 Review

The code I reviewed is from team blue.

1. Installation
I can download and install the code without any problem. There is a jar command to create a jar file, but I believe that is what is left from the last group since the file is named as "myisern-1-green.jar". All the QA tests are passed except for the Emma, which complains about the missing of the coverage.xml file. I would recommend the team to model their program after the StackStripes, which should easily fix this problem. There is a readme.html file comes with the package, but again, it is something from the last group.

2. Code format and conventions
The code do not violate much rules, however, there are some private variables are not commented in both the model and action bean. Other than this, there is no big problem.

3. Test case
Black box perspective: Only the listing functionality seems to be working correctly. Everything other than that seems incomplete. Adding or editing buttons would cause the program to crush.

White box perspective: Since Emma did not pass and there is currently no JUnit testing written, there is not much white box testing are being done.

Break da buggah: Clicking on the adding or editing button can crush the program.

4. User interface
The interface of website is very straight forward. The screen estate is well preserved since the program is still usable with only half of the monitor size. Although I would prefer some "Back" buttons that allows the users to navigate back to the previous page, as well as a link back to the homepage.

5. Summary and lesson learned
Overall, team blue's code still has a lot of work to be done in order to complete all the core functionalities. Consider this is only a work-in-progress result, it is acceptable. Besides that, the team seems to be on track and working towards the correct way.

MyISERN 1.2

Milestone release
User Guide
Developer Guide
Release Notes

This assignment turned out to be very repetitive, and also very difficult on the details. Although we have finished all the tasks, they are not done in a very elegant and efficient way.

The command line interface for inputting data is more complicated than I thought. By complicated, I mean the tons of if and else causes and several infinite loops inside almost every function. The backbone of the program is relatively simple, but that is only based on the assumption of the user do not input error data and knows what to input. A lot of effort has been spent on error checking. However, there are still some minor bugs in the program. We did not notice these bugs until we did the data input at the very end, where we did not know most of the data. If the data is complete and correct, the program will work perfectly fine. However, if the data is incomplete, the program will throw out a bunch of errors due to the schema requirement. Although the errors are all caught by the error checking and indicated, fixing them is such a harsh and tedious job.

What makes this assignment very repetitive and boring is the data input part. It is very often that the information is incomplete, and we will have to end up guessing. Also, because we assigned different data for different group members, such as one person does the researchers and another person does the organization, the program has a serious problem when merge these data together. The different names of organizations and researchers, which are chosen by different group members, give out many invalid links errors, even though they are essentially referring to a same organization or researcher.

This assignment once again showed the importance of face-to-face group work. At the last minute when we tried to figure out the data errors, we were using instant messengers, which was extremely inefficient. Also, a good planning ahead is still not achieved. Although we took our time to scratch out the structure of the program when we met, there are still many changes happened during the actual implementation. The failures to foresee these changes gave us quite a bit of troubles.

In terms of improvement to the system, there are many can be done. First is the Emma testing. We did not cover most of the methods in the editing class, which has many user input inside. Although Professor Johnson said it is not quite possible to do a detailed testing case for it in one week, I still feel unsatisfied for the low coverage of code. On the other hand, a more strict and accurate error checking should be implemented. The current system will still miss some error input.

Overall, this is another lengthy and hard assignment. Well, I think the good thing is I am starting to get used to it.

MyISERN 1.1 Review

This time we are able to choose the author to review. Therefore, I chose one of the graduate students group to see how they are doing differently from us. The author I picked was Andrew Wong from the Silver group.

Installation Review:

The source code is downloaded successfully. The Google project page also includes the wiki pages for user guide, develop guide, and the release notes. Following the instruction in the user guide, the jar file is successfully created. The verify task ran successfully also, which implies the JUnit, Checkstyle, PMD, and FindBugs are all passed as well. However, when I tried to execute some of the commands to generate the tables, I saw some really chaos and random display instead of a nicely organized table. It took me a while to figure this out: the author is doing the display based on the column numbers, which is obviously a number greater than the normal width of a command prompt window. I tried to resize my command prompt window to 800 columns, and then a nicely structured table finally showed up. The information is mostly horizontally listed, which requires a quite a big width for the window to display them correctly.

I would recommend the author to put this issue into the user guide, since normal users would not resize their command prompt window to verify the display, and they would simply consider the program is not working.

Code format and conventions review:
There are not many code violation can be found. However, for most of the files, the private data members are not documented. (For example, line 46-48 in MyIsernXmlLoader.java) Other than that, the code are well written and easy to read.

Test case review:
Black box perspective: The program does print out the information correctly when there is enough room to display them. However, duplicates and invalid links in the data files are not shown. I would expect to see, for example, at least an error message showing that there is duplicate researcher in my researchers XML file, so that I can go ahead and change it. Other than that, the black box testing seems to be working pretty well.

White box perspective: The Emma report is as follow:
Emma Coverage summary
class: 100% (1/1)
method: 97% (9/10)
block: 100% (497/508)
line: 100% (104/108)
Besides one method that has not been covered, all the other codes are tested. I looked into the Emma report and found out the non-tested method was a method that involves the enum type classes, which Andrew has been mentioned in the discussion. I personally do not know much about enum type, and it seems like the non-tested methods are somehow generated inside an enum class, which is not really inside the program. With the fact that the Java development team is probably responsible for the testing for the enum class, I consider the author did an excellent job in the white box testing.

Break da buggah: There is not really a way to "break" the program, but there are some ways to cause it malfunction, or at least, not functioning as expected. The first way is mentioned before, to execute the program in a normal command prompt window, which it does not print out information correctly. Secondly, the program does not print out error message most of the time for some invalid command calls. For instance, if I invoke the “-describe –all” task by passing something other than “researchers, organizations, collaborations”, the program will simple do nothing.

Summary and Lessons Learned:
Overall, the program is pretty well written. One thing I really like about is the modulization of the program. The author breaks down the program into loader, printer, query engine, checker, and command line parser. Consider this MyISERN project would be last for two semesters, it is definitely necessary to factor the program into different components, which does not interfere each other when one gets changed. I have been thinking to modulize my whole program, and now the Silver group gives me a very good example of doing this. Despite the tremendous amount of work to modulize my current chubby program, I think it is worth the time and effort to do so.

MyISERN-1.1

Milestone release
User Guide
Developer Guide
Release Notes

This is another very challenging assignment. Although I managed to accomplish all the tasks, I feel strongly there are many improvements can be made.

The hardest part of this assignment would be the unclear requirement. Although the requirements are posted on the course page, many of them are not clarified, especially the one that asks for link verification. Even though Professor Johnson answered it in the discussion, it still left me quite a bit of confusion. It seems like it could be done in several ways, and there are pros and cons in each way. I think this is what will happen in real life too. The customer do not always give clear requirement of what they want, or more often, even the customer themselves do not know what they want.

Another hard part of this assignment was the cooperation in the group. We started working for the different parts of the assignment, and then very soon we encountered the conflict problem while we were trying to commit our own files. Although we worked in different code, the conflict still appeared somehow. I think for student group project, commit conflict will be more often since students tend to work together around the same time and commit the code at the same time. Anyhow, we figured out the problem by merging or all updated to a same version.

Last hard part of this assignment is the testing-base design. Since our code are supposed to be tested by JUnit, I tried to avoid using void methods as much as I can. However, the requirements of this assignment seem to be still printing stuff out on the standard output. I could have made the methods return some values, such as true or false, or even a list or a map, but I really did not see the purpose of doing that. It simple violates the nature of the requirement. If the requirement is to print out something, then the methods should print out something without returning anything. After a little bit debate, we stick with the void methods.

For the possible improvement during the next assignment, I would first make sure what the framework of the program would be like, then list out all the classes, methods, and variables that will be implemented. In this way, everyone could work differently but still go towards a same goal. Besides, I would try to find a balance between the design and testing, and avoid the usage of void methods. After all, they are not good in the sense that they cannot be tested easily. Also, one thing I will definitely do is the issue organizations. In this assignment, our issue management was very poor, and I did not figure out how to edit an issue till the very end. It was simply a mess. In my opinion, the red team did very well on this. They divided the issue according to the requirement, thus for every commit there is always an issue to be related. This can avoid the redundant creation of the issues.

Overall, this assignment is not easy, but as usual, I learned a great deal of stuff from it.

MyISERN Review

I was assigned to review Jung Kim’s code this time, but by the time I was writing this review, I could not find the entry from his blog for the MyISERN assignment. Therefore, I went to his team’s Google project page to download the source code.

Installation Review:

The source code is downloaded successfully. There is no wiki page for the user guide or something like that, but after all this was not required in the previous assignment. I had no problem at all while trying to import the project into eclipse. I invoked the verify test in the command prompt, and it ran successfully. This implied the Checkstyle, PMD, FindBugs, and JUnit tests should all be passed.

Since the first MyISERN assignment is relatively simple, there is not much code added in the program. I can easily understand the code.

For the program execution, I invoked “ant jar” and it creates a jar without any problem. Then I invoke the jar file by “java –jar” command. The tables were printed out correctly. Overall, the program does what it supposes to do, and it functions correctly.

Code format and conventions review:

There are a few violations in the code:

File	Lines	Violation	Comment
MyIsernXmlLoader	152, 169, 196, *	EJS #7	Unnecessary blank line within a method
MyIsernXmlLoader	142, 159, 194, *	EJS #9	Pick more meaningful variable name or give it a comment
MyIsernXmlLoader	191	EJS #27	Name for collection should be plural

Test case review:

Black box perspective: The test does print out the table as expected. Other than that, the number of researchers, organizations, and collaboration are also tested, but that is given from the initial files. However, printing out the table is the only objective of the assignment, and the data are all given, there is not much black box testing can be done.

White box perspective: The Emma report is as follow:
Emma Coverage summary
class: 100% (1/1)
method: 90% (9/10)
block: 98% (497/508)
line: 96% (104/108)
Although the coverage is not 100%, it does not mean the testing is not sufficient from our experience of code coverage. By inspecting the testing case, I found out the reason for the missing coverage is that the main method has not been tested. However, since main method is “evil”, and JUnit is almost useless when it comes to testing of the standard output, I consider the author has done a fairly good job on the testing. Also, there is one line of error checking code is not covered. As mentioned above, the data for the assignment is given, thus an error input cannot be produce and the error checking will never be executed.

Break da buggah: I could break the program by running it outside its original folder, because the XML data files are defined such that they are located within the original folder. However, this seems a little bit too extreme to me because I think only a programmer that knows the internal structure of the program would know this could cause the program to fail.

Summary and Lessons Learned:
Overall, the program is pretty well written. It functions correctly and safely. One lesson I learned is that when the data is given, there is still no guarantee that the program will not go wrong. Furthermore, things tend to change a lot in real life, and errors usually emerge during the change. Another lessoned I learned is the importance of documentation. Not only the meaningful comment in the code is necessary, but also a user guide or manual is very helpful.

MyISERN-1.0

The source code can be downloaded from here.
Our Google project page is here.

The objective of this assignment is to get us started on building the social network application for ISERN, as well as start using SVN and Google project hosting. In this assignment, I learned about JAXB, XML Schema, group software development process, and I am more familiar with SVN, project hosting and XML.

JAXB: This application is very powerful when it pairs up with XML Schema. It took me a couple of hours to figure out how JAXB Marshaller class works. It basically provides a bridge to connect Java and XML. We can easily convert data that is defined by XML Schema to Java classes, and it is done almost automatically.

XML Schema: This is a way to define data in XML as far as what I understand right now. It might seem a little bit complicated at first, but it really makes sense once it is converted to Java classes by using the XJC compiler. Since XML is becoming a more and more popular standard to hold data, I think it would be very useful to learn about and get familiar with Schema.

SVN: It works very nicely for team development. By having a master copy of the working code, we can still share code and make progress without meeting face to face. I personally keep the source code for commit and update in a separate folder than the workspace folder in eclipse. This turned out to be a good choice I think, because some of my classmates informed me they are having problem when they commit or update the code straight from the workspace folder in eclipse.

Google project hosting: This turned out to be a much better service than what I expected. It helps us organize the project in a consistent manner. However, I do not really understand the purpose of the Wiki pages functionality. They seem to be only some text files with a .wiki extension. Also, the naming restriction of these Wiki pages is quite weird: It does not allow spaces or some special characters. Nonetheless, Google project hosting is satisfactory for me.

Group software development: I am lucky enough to have a good group for this assignment. We meet twice for long period of time during school, which made us finish most parts of assignment. We also tried pair-programming during the time we meet, and it was very helpful. Many errors or potential bugs, which might take several minutes to discover if we writing the code individually, were caught right at the time when we were writing the code. I do think it improve the speed of producing high quality code. For the Scrum methodology approach, since we were doing pair-programming, many tasks were accomplished together, but we still tried our best to make everyone to do everything.

JUnit: Once again, I feel a little powerless when it comes to void method test case in JUnit, especially the System.out.println() method. Since the objective of this assignment is to print out tables, which obviously should be using void method, the test cases are more or less impractical. They seem to be just for the purpose of fulfilling the Emma coverage. We tried to use Boolean as a return value to do error checking for these print methods, but the data in this assignment is all given by the XML files, thus we cannot even produce an error case in the testing, which makes the error case never being executed.