Home

##Koan Annotations for Java (^_^)

##What are Koans?

Essentially a Koan is a problem to solve.

Or from the Wikipedia article I think the most relevant explanation is:

Insight has to be demonstrated. A mere "answer" to a koan is not sufficient. The teacher is not looking for a specific answer, but for evidence that the disciple has grasped the state of mind expressed by the koan itself.

I think this is particularly relevant to the field of programming.

For this I am borrowing from the idea of the original Ruby Koans which involves the practitioner fixing a number of broken unit tests. Using a unit test framework allows for rapid feedback of the topics being discussed and using an IDE we can easily insert breakpoints to explore the code at run-time.

The fixture leans heavily on the JUnit framework.

##Example Koan

    @Koan
    public void makeTheProductOfIAndJ(){
        int i = 10;
        int j = 5;
        int product = 0;

        /* (@_@) Meditation starts here*/

        /* (^_^) */

        assertThat(product, is(50));
    }

##Java Concepts

###@RunWith(KoanRunner.class) Koan runner based on BlockJUnit4ClassRunner. Will execute as a Junit test and provide the usual green or red bar. Additionally provides the facility to write the solution into the file using @Enlightenment

###@Koan All methods marked with @Koan are picked up by the JUnit framework and executed with the KoanRunner. Analogous with to @Test

###@Enlighten When annotated with @Enlighten the KoanRunner will insert java code into the Koan class from the *.solution file. Thus providing the student with the solution.

###@Vex Provided to maintain the harmonious balance of enlightenment. Adding @Vex to a method will replace the current content of the marker tags with the starting problem. If no starting code is provided the solution defaults to empty.

##Usage for Masters

1. Koans live in a koan directory.

Example structure (maven)

/src
    /koan
        /java
            /com.my.package
                MyKoan.java
        /resources
            MyKoan.solution
    /main
    /test

2. A Koan class is annotated with @RunWith(KoanRunner.class).

3. A Koan is method annotated with @Koan.

4. A Koan should contain a start comment to indicate where a student should begin meditation i.e. // (@_@)

5. A Koan should contain an end comment to indicate where a student should reach enlightenment i.e. // (^_^)

6. A Koan should have a *.solution file that is named the same as the class e.g. MyKoan.solution. This lives in /koan/resources

7. A solution file should provide the code that is required to reach enlightenment. It should be presented by method name in square braces e.g.

   meditateOnHowToMakeIntIEqualToFive [ i = 5; ]

8. After mediation a Koan should use assertions to prove a grasshoppers enlightenment e.g. assertEquals(5, i);

##Usage for Grasshoppers

1. Completed your meditation with the comment markers (@_@) and end with (^_^)

2. If you fail to reach enlightenment ... try harder

3. If you still fail to reach enlightenment add @Enlighten to the Koan method and run the Koan again

4. Use @Vex to return to the original problem.

##Troubleshooting

Q) My IDE isn't updating when I use @Enlighten or @Vex.

A) Depending on your IDE and version, sometimes it will not refresh the source code. Learn the shortcut for manually refreshing the file. In IntelliJ IDEA this is Ctrl + Alt +Y

Q) The @Koan annotation does not support expected Exception paradigm similar as @Test(expected = MyException.class)

A) Expected exception handling via the annotation is deprecated in JUnit in favor of @Rule paradigm.