Original status
Returning to the programming project after a day of cycling and finishing some written coursework for another module, I was faced with a blur of methods (subroutines) written in the order I realised I needed them. These included some methods which were only there to test whether I could create, move and list my creatures.

The chronology followed the basic need to

1. create a swamp and its ogre
2. add enemies if luck so decided
3. draw a map of the swamp and its denizens
4. decide whether to have a battle
5. the actual battle (so far only pseudocode).

In short, my code was an inaccessible mess. It didn’t help that the code for the Swamp called code for ogres and enemies which are in separate files. Given that my code has to be read and understood, I needed to tidy it. (Currently, only my lecturer and I need to read my code. However, if I end up writing code for anyone else, they – and maybe later workers – will need to be able to read and modify it easily.)

Problem statement
Given that my code is an inaccessible blur, how can it be tidied?

Solution methodology
It is surely sensible to break any long piece of writing into chunks, i.e. chapters, headings and subheadings etc. So why not do the same to my code?

As far as I know, Java doesn’t allow headings and subheadings. I’m pretty sure there’s no such feature in the IDE I use. However, there are two comment styles:
//comment

and

/** *******************
* comment *
********************* */

The green style is used throughout to say what individual methods, bits of method and individual lines do. I believe the blue style is now used to feed the JavaDoc system and I’ve seen it used for header blocks (name of program, author(s), copyright status, etc). However, I’ve not yet got into JavaDoc.

Solution
So ‘chapters’ in my code are headed
/** *******************
* ALL CAPS *
********************* */

and ‘sections’ are headed
/** *******************
* lower case *
********************* */

Recommendations of how this should really be done are very welcome!

Corollary
Chunking my code and moving the methods so they fit the chunks has also been helpful in that I’ve isolated methods no longer used into a METHODS USED ONLY DURING DEVELOPMENT/TESTING. I feel I should get rid of them but I’m not sure. Recommendations are again very welcome.

I need to write a piece on how my code works, including some comment on development – so in this instance it might be better to keep them. Also, this code won’t be transmitted (unlike JavaScript doing stuff in your browser or naughty things to your computer) so it doesn’t **need** to be concise.

Current status
In my Swamp class, I now have chapters for

1. INSTANCE VARIABLES, CREATOR, SETTERS AND GETTERS
   8 items
2. CREATE AND ADD OGRE TO SWAMP
   2 methods
3. CREATE AND ADD ENEMIES TO SWAMP
   3 methods
4. DRAW MAP OF SWAMP, INCLUDING LOCATIONS OF ALL CREATURES
   1 method, which is currently horribly inefficient because all creatures are examined (swampSize)^^2 times
5. MOVE ALL CREATURES
   1 very short method that calls code from ‘Creature’ class
6. BATTLE
   This has 5 sections:
   • Find ogre’s location – this will be called each turn of the game and will update an instance variable (2 methods)
   • Find and record how many enemies are in ogre’s location (1 method)
   • Decide whether there should be a battle (1 method)
   • Actual battle (3 methods)
   • Methods for removing creatures (2 methods)

    

7. METHODS USED ONLY DURING DEVELOPMENT/TESTING
   5 methods

My Creature class has

1. INSTANCE VARIABLES, CREATOR, SETTERS AND GETTERS
   13 items
2. MOVE THE CREATURE
   2 methods – although I should split one of these into 3 separate methods
3. WHERE IS THE CREATURE?
   1 method, currently unused.

My Ogre and Enemy classes just have creator methods, so don’t need chunking.