The Art of Shining within Steel Confines

Freedom in America doesn't come cheap. You still have to follow the laws within society, which are as strict as steel, in order to be considered a good and civilized citizen. The same goes in the software engineering world. Most of you will find yourselves in a business that is not run by you. There is little freedom to code in whatever way you desire or to say no if a software review is requested of you when you have so many other matters of importance to attend to. Midway through this semester, I've learned that I've missed out on so much over the past two years. I thought that if I followed the norms and did all that was required of me in my classes, I'd be on the road to success. Apparently, that thinking had always been far off-key. The following questions and my answers to them reveal that shining within steel confines is an art, not a sequential computer program as I had thought it to be all along.

1) What is the difference between standards and feedback? What are the many ways in which you receive feedback in this class?

Standards and feedback are vital for the three prime directives of open source software. Standards are required to allow people to work together in a way that would eliminate unnecessary unexpected events and technical issues. With standards in place, people can worry less about doing the right thing and focus more on the quality of their communication with others. Feedback, on the other hand, is the key to improvement. Success in the software engineering world is not an end goal but constant improvement. With constant feedback, success can be achieved. While standards provide structure, feedback shapes personal and professional growth. Ways in which we receive feedback in class are from partners or group members, other class members, the professor, the designated mailing list, automated quality assurance tools such as Checkstyle or FindBugs, and the outside online community.

2) List the four ways in which your professional persona is assessed in class and elaborate on each of them.

Your professional persona is how the world views you as a professional - a person with valued thoughts and valued skills. Here are the four ways in which professional persona is assessed in class:

1. professional portfolio - A place you can boast all about yourself (and only yourself). Do so in a professional manner, of course. This means no going into endless anecdotes about your personal life. Instead, highlight your industry-relevant skills and achievements. Detailing projects you have worked on is valuable, as it could give potential employers deeper insight into what you're actually capable of.

2. online engineering log - A blazing hub for your professional thoughts on industry-relevant tools and matters. This time, the focus is not on yourself but on those tools and matters. Write for the world, but keep in mind that your target audience is potential employers. They would use this log to assess your ability to communicate effectively through writing.

3. participation in professional social networks - A portal into valuable unending knowledge. This allows potential employers to witness firsthand how you contribute to industry-relevant discussions and how much you care about colleagues and others in the business. Furthermore, this will contribute to your personal and professional growth, giving you a broad range of views that you simply cannot obtain from just working with one or a few companies.

4. participation in open source projects - A concrete showcase of your expertise. Anyone could say they could write code, but the question in most employers' minds is, How well could you write code? Open source projects allow employers to examine actual code you've written and shared with the world. It also gives them an idea of how well you assimilate into a group mold: Do you follow your own standards or the standards of the existing code?

3) Name one way, outside of class, that you are encouraged to enhance your professional persona. How would this benefit you?

Participation in technical societies and activities would only further enhance your professional persona. Such technical societies include IEEE, ACM, SWE, and Honolulu Coders. Some technical activities are to chat in the IRC, compete in TopCoder competitions, and practice information security skills on wargaming websites such as SmashTheStack.org. Participating in any of these and more is a remarkable benefit because you could gain skills and knowledge that you would otherwise not gain from reading a textbook or taking a class. Such participation gives you a lot more to talk about during job interviews. In addition, if you win in a technical competition, you could add that to your resume and professional portfolio.

4) What are the three questions to ask yourself when conducting a software review? Why is each of these important?

A software review is a vehicle for further growth of technical skills and knowledge. The ability to assess others' coding faults is crucial and helps you to better assess your own code. In addition, the software engineer's code you're reviewing may have functionality very much different from your own, even if the two of you are working on the same product. Therefore, in the long run, it's always best to understand at least the key functionality of the code you're assessing as well as where the vulnerabilities may lie so as not to repeat the same mistakes and gain a better understanding of the product as a whole. When conducting a "decent" software review, here are the three questions to ask yourself:

1. Is my review revealing problems?
Importance: A software review takes time away from writing more code. Why conduct a software review when it won't be accomplishing its purpose? Its purpose, in fact, is to reveal problems with someone else's code - problems they easily skip over or normally can't find on their own. On the job, it's a business because time is money. In general, make sure what you do is relevant and that you achieve the purpose. Otherwise, you're not helping the business, the other software engineer, the customers, or yourself.

2. Is my review increasing understanding?
Importance: What good is a software review when all you've written sounds like gibberish to its target audience - the software engineer who has written the code? All your efforts to improve the system would go to waste if you won't take a little extra time and effort to enhance the software engineer's understanding of their own code. In the process, you will only be helping yourself feel better about yourself for helping someone else and feel better in general for gaining deeper insight into the product under development.

3. Is my review doing (1) and (2) efficiently?
Importance: Yes, take a little extra time and effort - but not a whole lot! The key to "time is money" in a business is balance. There should always be a balance between every component of your role on a software development team. What good is a software review that takes two weeks to complete when a report summary of new updates to a system is required each week? Be able to use good judgment, common sense, and past mistakes to assess how long a particular review for particular pieces of code should take.

5) Give some examples of why the saying, "It's [the professor's] way or the highway," is quite prevalent in this class and relate it to the real world.

Part of the answer lies in the introduction to this post, in which there is little room for freedom when software engineers must conform to standards and follow norms. But of course, without it, chaos would ensue. As we all know, understanding and debugging another's code is quite different from doing so with your own. For the purposes of this class, one example of "the professor's way" is our use of the Eclipse IDE, which goes hand-in-hand with our use of Java. Eclipse is used mainly because it runs on multiple OS platforms, it is free open source, and it is easy to integrate its use with other tools (such as Ant, JUnit, and SVN). We code with Java, even though there are so many other useful languages, because it is one of the most supported languages today with a complete API and a smorgasbord of tools at its disposal. I can very well imagine if we were allowed to use other IDEs or languages in this class - we would certainly get less work accomplished and acquire software engineering skills and knowledge at a much slower rate. In relation to the real world, the chaos and destruction would be tenfold and much more serious and irreversible. Nevertheless, there's an art to shining within steel confines: Follow their way and never take it to scorn. If you learn what you can outside the edges, you're paving the highway and calling it your own. In time, others will recognize you for it.

Submersion into Subversion

These days, when we hear brand names such as Apple, Microsoft, and Google, we think of one software, one hardware, one product. We hardly stop to think of what lies past the name, past the "one." But in fact, it is a multitude of people who makes a product, not just one company. And they make a product in time for its launch date, continuing to provide updates and support afterwards. Let's focus on the software for now. How is it possible not to transform into some wild green-eyed lost soul due to millions of lines of code, written not just by you, but by others as well? The answer lies in configuration management.

Configuration management tracks the state or configuration of a system at any point in time so that changes made to the system are logged and different versions of the system, old or new, can be utilized for different purposes. Configuration management aims to solve the issues that arise when multiple programmers work on a single software product simultaneously. Even with simple compilation or verification issues, the quick fixes may not be apparent until hours or days into debugging. But with a configuration management tool, this could be avoided, since the previous version of the system, before the incriminating changes were made, could be downloaded.

Google Project Hosting and SmartSVN for Mac (TortoiseSVN for Windows) is an excellent duo for amateur developers to kickoff with configuration management. Add Robocode or a working project into the mix along with classmates or friends for committers, then you could host your very own project in no time. Including easily accessible User and Developer Guides is the standard and allows others to know that you intend to treat them and your work on a professional level. The checkout URL repository on Google Project Hosting appears under the Source tab, and Subversion (SmartSVN or TortoiseSVN) provides the host and committers with commit and add access. The Changes link under the Source tab and the Updates link under the Project Home tab display any changes made on the site.

Overall, this was quite a refreshing learning activity and was none too difficult at all. The only minor hurdle was the initial attempt to get my project files uploaded to the trunk directory of my robocode-bma-[nameofrobot] project. Otherwise, brief communication with my classmates and watching the screencasts made this an easy dive into configuration management.

A Prime Example of What It Takes to Not Win at the Robocode Tournament

1. Overview
We have all been recently promoted to a belt of the next higher level and have now been asked to compete in the once-per-course Robocode Tournament. Am I strong enough? Have I trained enough? Do I have what it takes? Well, it was time to take one step at a time and see for myself.

To start off, I used the Robocode Katas Assignment as a foundation upon which to build my competitive robot. Notably, I made use of HitWallEvent from Position02, movement from Position04 and Position05, and firing tactics from Boom03 and Boom04. Of course, bunching all this code up together in a single robot is not ideal. So I then focused my efforts on beating one sample robot at a time.

In an ideal world, my main objective would be to win the Robocode Tournament if I had had more time to work on this. However, lack of extra time was indeed the case, and so, my main objective was set to the minimal requirements: to defeat the eight sample robots, namely, SittingDuck, Walls, RamFire, SpinBot, Crazy, Fire, Corners, and Tracker.

2. Design
A. Movement
My robot's basic movement is that it always moves to the center at the start of a round, so as to maximize its chances of getting closer to the enemy robot, since the closer it is, the greater its firepower. The only other time my robot moves is when it dodges (moves ahead by 100 pixels), if the following two conditions are met: its distance from the enemy is greater than 200 and its energy is less than 40.

B. Targeting
In the run method, the radar constantly turns in the while true loop (but this only happens if the robot hasn't chosen a target yet). Targeting is calculated with a simple equation in the method trackTactic: my robot's heading minus its gun's heading plus the enemy's bearing. The gun should only turn towards the enemy if it is not already pointing at said enemy. For some reason, however, my robot still turns its gun at times even though it has been constantly firing at the enemy who has been standing in the same location.

C. Firing
An enemy robot is fired at once it is detected. My robot's firepower has strengths 1, 2, and 3; the closer the enemy is, the weaker the firepower, and the farther the enemy is, the stronger the firepower.

Beating one robot at a time:

R1. SittingDuck
A no-brainer. This robot doesn't do anything, so there's no strategy required in beating it.

R2. Fire
My code for beating Fire certainly isn't the most efficient implementation. But it works. Fire helped the logic in constructing the onHitByBullet method, which triggers a HitByBulletEvent if the robot is hit by a bullet. The bearing of the bullet is the direction in degrees relative to my robot's heading. Basically, if the robot is not facing the bullet dead on, just move forward by a few pixels. But of course, if the bullet is hitting the robot in the face, turn right by a few degrees before moving forward.

R3. RamFire
While the Fire sample robot centers on the onHitByBullet method, RamFire centers on the onHitRobot method, since that is exactly what RamFire does: hits the enemy robot. I tried firing twice with a maximum power of 3 and to my surprise, it beat RamFire a few times. However, I wasn't satisfied with two lines of code, so I had my robot fire only if its energy was greater than or equal to the enemy's. If my robot's energy was less, then it should back away. However, this tactic did not work well at all, since the extra time taken in moving backwards allowed RamFire to move forward in the same amount, corner my robot into a wall, and beat it to a pulp each time. In the end, I stuck with two lines of code that at least beat RamFire sometimes instead of never.

R4. Crazy
Crazy moves around a whole lot, which is good for evasion but not exactly a great evasion tactic, especially since my robot was able to win most of the time against it. I used a combination of two robot katas (namely, Boom03 and Boom04) to win against Crazy. The overall strategy is, the further away Crazy is, it's still good to try and shoot at it but with minimal firepower, since the majority of the time, my robot missed like crazy. And of course, stronger firepower was the way to go when crazy was nearer to my robot; it was the only time for redemption. Even though missing was still a high percentage here, getting in a few good hits was worth it.

R5. Corners
The tactics that Corners uses are simple but not quite strategic enough: pick any of the four corners, stay there, and shoot at the enemy. To beat Corners, I focused on the onHitByBullet method, since my robot seemed to be getting hit quite a bit. I noticed, however, that Corners only uses a firepower of 1. So instead of dodging all the time whenever my robot got hit by a bullet, I only made it dodge if its energy was less than 50 (half of the initial energy, which is 100) or if the bullet that hit it had a firepower greater than 1. Again, this is not the best strategy, but it beat Corners on more than one occasion.

R6. Tracker
Unfortunately, my onHitByBullet method worked for Corners but not for Tracker. Tracker follows the enemy and fires with maximum firepower of 3 at all times. Because Tracker always ended up close to my robot. This meant that even if my robot had more health and fired with maximum firepower at Tracker, Tracker would win because my robot would begin to dodge if its health was less than 50. This wasn't a good idea at all, as it always made my robot lose. So in the end, I created a boolean variable called "dodge" and initially set it to false, only to be true under certain conditions. In Tracker's case, dodge is set to true only if the distance between Tracker and my robot is greater than 200 pixels and my robot's energy is less than 40. But what really got my robot to beat Tracker was to change the requirement for maximum firepower of 3. By being more lenient on the requirement (the distance between my robot and the enemy robot is less than or equal to 300 pixels instead of 100), my robot had the upper hand on Tracker.

R7. Walls
I tried what I could against Walls, including using an onBulletMissed method to increase an integer count on the number of missed bullets my robot would fire. If this was above a certain number in the onScannedRobot method, then this would trigger a method to move my robot to a corner of the map. Unfortunately, before my robot ever got close enough to block Walls within its path, it often became an open target for Walls. I ended up having to delete anything to do with Walls. At this point, I don't think my robot can ever beat walls.

R8. SpinBot
At this point, my robot had enough basic skills to be capable of beating SpinBot on very minor occasions. The spawning location at the start of a round was one determining factor, as well as my robot's heading relative to SpinBot's overall position as he travels in circles. But in short, SpinBot was the victor.

3. Results
I used the two JUnit test classes for Corners and Fire to run 100 battles against each sample robot and calculated what percentage of the battles my robot won.

Sample robots that my robot can reliably beat:
- SittingDuck (100/100, 100%)
- Crazy (75/100, 75%)
- Fire (85/100, 85%)
- Corners (97/100, 97%)
- Tracker (85/100, 85%)
- RamFire (74/100, 74%)

Sample robots that my robot cannot reliably beat:
- Walls (0/100, 0%)
- SpinBot (7/100, 7%)

The detailed explanation of why my design worked for the majority and yet didn't quite work for some is located under the "Design" section, entitled "Beating one robot at a time."

In order to do better, I would improve my design by examining even more cases and setting more boolean variables or running counts on certain items, such as the number of times its bullets miss or the number of times it gets hit by a bullet. If the robot is in a certain state, then a particular tactic would be used instead.

4. Testing
I wrote two acceptance tests, two behavioral tests, and two unit test. The two acceptance tests simply test whether or not my robot beats Corners and Fire. The two behavioral tests test my robots movement and firing (there wasn't much strategy to targeting, so I left that part out). Lastly, the three unit tests checked to see whether or not my robot has dodged at least once in an entire battle and whether or not my robot has fired twice upon colliding into an enemy robot. Both JaCoCo and JUnit run successfully.

5. Lessons Learned
In future, instead of focusing all my energy into coding for one-on-one matches, I would develop strategies for matches consisting of more than two robots. In regards to software engineering, I have learned (from this project) that it is helpful to write about what you do along the way instead of writing about it after you are finished. This also minimizes error. From a software development perspective, I would definitely give myself more time to work on the project.

Manual Automation Katas

Early in the 20th century, America moved from hands-on factory labor to newer and better automated processes - a much-needed match for America's growing population and therefore, growing demands for supplies. This same concept applies to software. As software packages grew in the number of lines of code, the need arose for automated processes. Enter scripting languages such as Make and build systems such as Apache Ant. Apache Ant or Ant (an acronym for "another neat tool") is a software build system tool that allows for the compilation, execution, testing, and documentation of Java and C/C++ applications. Ant works in conjunction with Ivy. Ivy downloads and maintains the libraries required for software projects. Ant is supposedly easy to learn, especially if the "kata" principle - the repeated practice of form - from martial arts is applied.

1st Kata: Ant Hello World
If there's one thing a software developer will never say goodbye to, it's hello. <\echo\> (imagine that the backslashes aren't there; the same goes for the rest of the tags in this post) is to Ant as "System.out.println()" is to Java. Hello World . . . Hello, My First Ant Build Script. A cinch, a cinch, yes it was.

2nd Kata: Ant Immutable Properties
It's integral that Ant, part dependency manager, should have immutable properties (defined by <\property\> tags), as demonstrated by this kata in which I defined two properties of the same name, assigned them different values (first "1" and then "2"), and printed out the value of the property. Any guesses as to which value was "echoed" to screen?

3rd Kata: Ant Dependencies
Ant's dependency management operates in a very straightforward manner: <\target\> is to be executed only if the "depends" attribute is fulfilled. And if "depends" does not exist, then <\target\> is free to run. In other words: IF "depends" is fulfilled, THEN <\target\> executes. <\project\> is to Ant as "class" is to Java. The attribute of <\project\> called "default" specifies the main <\target\> that a build file should run. This dependency management was demonstrated by implementing the following:

*foo should depend upon bar.
*bar should depend upon baz and elmo in that order.
*baz depends upon qux.
*qux depends upon elmo.
*elmo has no dependencies.

Before running the build script, I had to guess in what order the targets were called, given that "foo" is the default target. I guessed the following: elmo, qux, baz, bar, foo. Right? Yes. Why? foo can't run without bar, and bar can't run without baz and elmo, but baz can't run without qux, which relies on elmo. elmo is the only one without dependencies, so it executes first. qux runs next, allowing baz to run after it. Now that baz and elmo have been executed, bar runs. Lastly, foo runs (it had been waiting on bar this whole time).

The second task was to change the script and make elmo depend upon bar. I had an idea as to what would happen, but I wasn't so sure what would print out. As wonderful as it could ever get, Ant knew exactly what went wrong: circular dependency, since bar ends up depending upon itself.

4th Kata: Hello Ant Compilation
A HelloAnt.java file that prints "Hello Ant" to screen? Easy. Now getting the build file to succeed was all a matter of examining the existing Ant code and modeling my "compile" <\target\> after it. With the use of the <\mkdir\> and <\javac\> tags, I was able to successfully automate the compilation of a Java file.

5th Kata: Hello Ant Execution
This kata was the trickiest so far; I couldn't find an example in the Ant build files I downloaded as part of the Ant package, so I had to search this one up. There were a few unsuccessful executions (using Terminal on a Mac), but I was able to determine that "classname" (name of the Java class, excluding the .class extension) and "classpath" (the location of the Java class file) were the only <\java\> attributes needed. I had success compiling when HelloAnt.java was in the default package, but after moving it to the edu.hawaii.ics314 package, it simply would not compile. Thanks to Jordan Takayama's's blog, I found out that the "classname" attribute should be set to "edu.hawaii.ics314.HelloAnt" and the "classpath" attribute should be set to the "classes" directory. Lastly, this was the first kata that made use of the <\import\> tag (the "compile" build script had to be imported), which is very similar to the #include directive of C/C++.

6th Kata: Hello Ant Documentation
Generating JavaDocs by entering a single command has never been made easier. However, before I could get this to work, I had to create an "overview.html" file (in the "src" folder but outside of the package) and a "package.html" file (in the package). I then made sure that any properties used in the <\javadoc\> tag were specified in my build system before I ran the script file to generate the JavaDocs.

7th Kata: Cleaning Hello Ant
This was pretty straightforward. Again, I modeled my "clean" target after already-existing Ant code. A simple <\delete\> tag did the trick and deletes the "build" directory if "clean" is listed as a dependency.

8th Kata: Packaging Hello Ant
This kata was extremely frustrating at first because I could not for the life of me get my zip file to unzip into a single directory. I tried and tried it my way, trying to ignore existing code in the hopes that it would work for me with a few lines of code. In the end, I had to look at the existing code (from PMJ-DaCruzer's dist.build.xml file) and model my code after that. I learned that it is perhaps impossible to unzip files into a single folder without copying files to a directory within a temporary directory first.

Figure 1: One simple command (ant -f dist.helloant.build.xml) for distribution

In conclusion, Apache Ant is a very powerful tool, designed to make the distribution of a Java project more user-friendly and efficient. Build systems help us automate distribution, proving to be a bit troublesome when one attempts to go against the flow, but once one learns to adapt to it, the raging river becomes easier to navigate.

Mixing Martial Arts with Robots and Coding

So how does one mix martial arts with programming? It's simple: you take the general principles from one and apply them to the other. The general principle in question that is of particular interest to programmers is called the "coding kata." In martial arts, basic form is practiced over and over in simple, repetitive movements called katas. It's no wonder martial arts can appear as graceful as professional ballet and figure skating. This same principle of katas can be applied to coding and is especially useful when one is learning to program in a new language or learning the workings of an open source project.

And the robots come marching in . . . in the form of the renowned Robocode open source project, initiated by former IBM employee Matthew Nelson. With Robocode, one could code their own robots from less than a minute to days on end, depending upon the level of competitiveness the robot is intended to have. The premise for Robocode, inspired by Nelson, is that coding games in Java could be fun and efficient. Indeed, it wasn't - at least, not at first.

Two years ago, I wanted to join a Robocode competition but didn't know how to begin, since I was a Java newbie. If only I had learned about the coding kata back then, then perhaps I would have been able to code at least one simple robot. Indeed, this coding kata is a life-changer.

Luckily, I was given the chance to work on Robocode again this year. The best way to build a competitive robot is definitely to start from the basics, as the Karate Kid films show. I learned, to my surprise, that coding robots was not as difficult as I had made them out to be. It was fun learning bits and pieces of trigonometry all over again. What caught my attention was that robots are like little kids - they won't know when to get out of the way of other robots, just as little kids won't know to look left and right before crossing a street.

Overall, I feel good about the assignment (having implemented all behaviors; I just don't feel too good about the commenting) - it was a treat, in fact, and didn't feel like homework. Coding robots is fun, especially when you're learning from others as well, all practicing the same coding form in order to achieve greater things, such as competitive robots, later down the road.

FizzBuzz Java Implementation Analysis in Eclipse

It took me approximately 25 minutes to implement (with good citizenship) and verify (line-by-line) the FizzBuzz program.  Summary: Rough implementation - 10 minutes; Code-polishing - 15 minutes

Before our first lecture class for Software Engineering, I have not programmed in Java for months. Given this task to implement FizzBuzz in Java, I took about 10 minutes to code FizzBuzz off the top of my head (and partially from what I could remember from last week) and run it with an at-a-glance "passed" for verification of correct output. However, at this 10-minute mark, I knew I had yet to appropriately verify my code, figure out how to place it in the proper Java package (edu.hawaii.ics314, in this case), and comment my code for good programmer citizenship's sake. With fellow classmate Jason Yeo's help, I discovered that I had always been missing one simple step to placing a Java source file in a custom package, and that step is to specify a name for the "Package" text field upon creation of a new Java class. As can be seen in the following figure, I had multiple packages before I made the right one (and later got rid of the others):

Figure 1: Multiple packages before creating the right one

Commenting each subsection of the code took only a few minutes.  It was the line-by-line verification of the correct output that comprised the bulk of the 15 extra minutes I spent to polish my code.  Each of the "FizzBuzz" and "Buzz" outputs were a given, since multiples of 15 and 5 are hard to miss.  In order to verify the "Fizz" multiples of 3, I mentally added each multiple's digits and divided the resulting sum by 3.  In the near future, I shall learn to use JUnit to test my code instead of this human error-prone line-by-line verification method.

In conclusion, I learned that writing the code itself is a downhill slide.  It's the uphill climb - the polishing of code and learning of new concepts to polish it even better - that takes more time, but in the end, it matters most.

Figure 2: The proper package, carefully-constructed comments, and line-by-line verification


Figure 3: My Java Implementation of the FizzBuzz Program

Logisim: An Essential for Every ICS 331 Student

An Assessment of Open Source Software against the Three Prime Directives for Open Source Software Engineering

Last semester, I took ICS 331 with Dr. Curtis Ikehara, which is a course entitled "Logic Design & Microprocessors," and about each week, he would assign us a lab assignment using our breadboards.  In other words, understanding and building circuits was a huge portion of the class, and if only I had begun to think sooner about delving into the world of open source software, then I would have saved myself from unnecessary eraser markings and trouble.

Overview

Logisim is exactly as its name implies: a simulation of logic - of digital logic circuits, to be more specific.  Its main function is to serve as a user-friendly interface for designing, building, and simulating digital logic circuits.  More information can be found at its SourceForge.net website and Project Home website.  In reference to Dr. Philip Johnson's Three Prime Directives, my assessment of Logisim is as follows.

Prime Directive #1: The system successfully accomplishes a useful task.

In less than five minutes, I was able to discover Logisim's most basic function without reading any tutorials by replicating a XOR circuit consisting entirely of NAND gates, as shown in the image below.  After accessing the "Help" menu, I discovered the feature of building circuits automatically using input from a truth table, which is a useful function for building especially complex circuits.  This program also features hierarchical circuit design, or the ability to use saved/already-existing circuits as portions of other circuits.  In short, this system, without a doubt, successfully accomplishes a useful task (and more).

Figure 1: XOR circuit consisting entirely of NAND gates

Figure 2: The "Help" Documentation

Prime Directive #2: An external user can successfully install and use the system.

It took about a minute or so to download, install, and run the program (the latter accomplished by a simple double-click on the OR gate icon labeled "Logisim").  For download and installation support, straightforward and concise "Getting Logisim" directions are found on the Project Home website, upon clicking the "Download" link on the left panel.

As mentioned above in the first prime directive, the interface is simple enough in design that the average user can construct a circuit in under five minutes.  Click once (but do not hold down) on a logic component icon, such as a gate, move the mouse pointer over to the dotted area, position the icon, and place it down by clicking once more.  Hovering the mouse pointer over the blue markings behind a gate, for example, creates a momentary green circle around the specific marking.  This circle indicates a point from which the user can click, hold, and drag a solid line from one icon to another.  The entire contents of the "Help" documentaion for Logisim can be found offline on the "Help" toolbar within the program or online at the developer's website.  In short, this system is extremely easy to successfully install and use.

Prime Directive #3: An external developer can successfully understand and enhance the system.

Bugs, Feature Requests, and Support Requests could be reported/requested using the "Tracker" menu on Logisim's SourceForge.net toolbar.  The News information under the "Develop" menu includes version release notes; the 2.7.1 entry here introduces a mailing list for development updates, which anyone can subscribe to at this link.  There is also a separate Logisim Developers' mailing list and Google Group found on the "Support" menu.

Features, bug fixes, and design changes are highlighted on Logisim's Project Home website under "Release History," and Carl Burch, the original developer, also provides his e-mail address in the "Comments" section in case the SourceForge.net resources do not serve a user's needs.

At Logisim's "Develop" page on SourceForge.net, clicking the "browse code" link under "Repositories" displays a page that shows the file/folder name, the number of revisions made to that file/folder, the "Age" (stating the elapsed time since the last revision), the "Author" (who made the last revision), and the last log comment/entry.  One way to access the source files is by clicking on the "Download GNU tarball" link.  Another way to access them is by decompressing the jar file included with the initial download of the Logisim software.

In regards to the Java source code, I feel that there is a significant lack of comments in each of the ten sample files I have opened.  Most of the comments are something along the lines of "access methods" or short three- to five-word one-liners.  Only one of the files I opened actually had a few comments within a method itself.  This style of commenting is in no way beneficial on my part or, as I can imagine, on anyone else's.  Hence, despite the fact that some pretty solid support and documentation exists for the Logisim open source software, it does not meet the last prime directive because its source files are not well-outlined and well-commented.  Nevertheless, I still recommend that every ICS 331 student take advantage of this software as soon as humanly possible.