-
Notifications
You must be signed in to change notification settings - Fork 0
episode 001
The idea behind okoze is simple:
Take a photograph of a pencil puzzle printed on paper, convert it into digital data, and solve it on a computer.
I actually want to use such an application myself. There are many pencil puzzles that I enjoy solving on paper, and I would like to explore what happens when they become digital.
Solving a puzzle slowly with paper and pencil is enjoyable in its own way. But digitalizing a puzzle can add different possibilities.
For example:
- Undo and redo are easy.
- You can use an eraser as many times as you like without damaging the paper.
- The application might be able to tell you whether your answer is actually correct.
- A puzzle you have already solved can be played again as a time trial.
- Digital data makes it possible to experiment with ways of displaying or interacting with a puzzle that would be difficult on paper.
Who knows? Perhaps one day something like okoze might even be usable through smart glasses.
The puzzle itself, however, is not the main subject of this series.
The real subject is software development.
I have been developing software for many years. During that time, I have tried various approaches to software development and gradually developed a way of working that suits me.
However, I still have questions about how a small software project should best be developed, especially when it is being developed by an individual.
And now there is another major change: AI can write a substantial part of the actual code.
So I would like to explore software development again by actually developing a small application and observing what works and what does not.
Note
This is not a series about presenting an ideal software development methodology.
It is an experiment in which I use my own development style, try new ideas when appropriate, and record what happens.
okoze is the subject I have chosen to explore this with.
I want to record not only the code, but also the requirements, design decisions, development process, experiments, mistakes, and changes in direction along the way.
There are two reasons.
The first is practical:
I want to use it myself.
The second is that I do not want okoze to remain a single-purpose puzzle application.
My long-term idea is to build a small framework for logical puzzles and add different puzzle types as plugins.
The application itself would provide common functions such as:
- importing, displaying, and editing puzzle images
- rendering the puzzle
- saving and loading puzzles
- undo and redo
- common user-interface functions
- common solver-related functions
Individual puzzle types would then be implemented as plugins.
I do not intend to build all of this at once.
The first goal is simply to make Sudoku playable.
After that, I would like to add Slitherlink and use it as an opportunity to turn the puzzle-specific part into a plugin.
This gives me a concrete application to build while also giving me interesting software-design problems to explore.
There is no particular reason to finish it quickly.
In fact, I deliberately want to develop it slowly.
This series will not simply present the finished code.
I want to record how I arrived at the code.
In particular, I want to show:
- what I was trying to achieve
- how I designed it
- what alternatives I considered
- why I chose one design over another
- what experiments I performed
- what I learned after implementing something
- what I changed when my original idea turned out to be wrong
Sometimes a design will turn out to be wrong.
That is fine.
Changing a design after discovering a problem is a normal part of software development. I want to record those changes rather than hide them behind the final version of the code.
The actual development process is therefore part of the subject of this series.
I have developed my own way of working over many years.
One simple habit is to write down what I am going to implement before writing the code.
It can be very small.
Sometimes a single sentence is enough.
I also write down the test cases that will tell me whether the feature is complete.
The basic procedure is:
- Write down what I am going to implement.
- Write down the test cases.
- Implement what I wrote down.
- Do not implement things that I did not write down.
This sounds almost too simple.
The point is simply to put the next piece of work into words before implementing it.
Tip
The specification does not have to be a formal document.
A single sentence on a piece of paper is enough to start with.
The first version of these notes does not need to be electronic.
In fact, I often find a small piece of scrap paper more convenient than a notebook.
I can write something down quickly, move the paper around, group related notes, and throw it away when it is no longer needed.
Once a decision becomes important, I can transfer it into digital form, either by typing it or, when appropriate, simply taking a photograph of the note.
The same applies to test cases.
I find it useful to have a small, concrete description of what should work before I start implementing it.
This way of working was partly inspired by ideas from Getting Things Done (GTD). The important point for me is not to keep everything in my head.
I find this to be a low-stress way of developing software.
Note
This is my personal development style, not a recommendation that everyone should follow.
Developers working in an organization will normally have to follow the processes and standards of that organization.
This series is mainly aimed at individual developers, and perhaps small teams with relatively loose processes.
More importantly, I will not merely describe this approach.
I will actually use it while developing okoze.
For each implementation episode, I intend to begin by writing down:
- the feature to be implemented
- the test cases
The goal of the episode is then to make those tests pass and to complete part of the feature described at the beginning.
Sometimes I may run out of time.
Sometimes the implementation may fail.
That is fine too.
The result is part of the development record.
Some parts of my development process have been used for many years. Other parts are new experiments.
The development method itself is therefore also subject to trial and error.
As the project progresses, I may add, change, or remove development practices.
I do not know exactly where this project will go.
I have a rough goal for okoze v1, but I do not want to design the entire application before writing the first line of code.
Instead, I will make a small design, implement it, learn something, and then decide what to do next.
The same applies to this series.
The way I develop the software may change.
The way I write the articles may change too.
That is part of the experiment.
Note
The development process described in an early episode may not be the process I use later.
I intend to keep the development record as it actually happens rather than rewriting the past to make everything look consistent.
For now, the plan is simple:
Develop a little. Think a lot. Write about it. Repeat.
Let's see where this takes us.
okoze is a temporary development name.
When the application is eventually completed, I may give it a different product name.
The name comes from a fish called oni-okoze (オニオコゼ), whose scientific name is Inimicus japonicus. Its English common name is devil stinger.
It is not a particularly beautiful fish, but it is known in Japan as a delicious and highly prized fish.
I happen to have several books about fish on my bookshelf, since I like fish.
One day I was flipping through one of them looking for a suitable name for the project, and I came across the oni-okoze.
It seemed like an appropriate name for a software project.
So okoze it became.