Category Archives: programming

The Autonomous SDLC: When Code Becomes Substrate

In my last two posts, I dove into an implementation of AI agents in the area of software design, specifically having different LLMs debate a design problem. At the end of my last post I shared some initial thoughts on how this fits into a bigger picture of software development life cycle in the age of AI.

I’ve argued before that I believe AI has more potential than simply generating code faster than humans. AI-based design debates are, I believe, just one component in a broader ecosystem of techniques and tools that mechanize a lot of the process of evolving and developing a software-based system. Software development involves much more than simply coding the desired behavior. Taken from this perspective, program code becomes another substrate on the path between human thought and working software. It is a substrate increasingly detached from human supervision¹.

Consider the combination of:

Can we envision a process where a human provides the necessary definition of required functionality, with some non-functional requirement thrown in, and a machine, driven by AI, picks it up and iterates through a continuous loop to build and evolve the system?

I imagine something like this:

(arrow direction represents data flow – read and write direction)

Where a human developer² provides requirements to implement in the system, goes through some clarification Q&A cycle, but eventually hands off the design and implementation to a set of AI agents that break down the requirements to an actionable implementation plan, and implement it up to deployment. The new code is then deployed, architecture and code updated, and they become the basis for a new feature/bug fix to be implemented. This cycle proceeds as long as new requirements (including bug reports) are fed into the system. The system evolves by a set of agents that cooperate on specific tasks, handing off the different artifacts and making changes, potentially in several iterations.

The concept of fitness functions is crucial. We know that LLMs require a way to perceive the environment, and perceive the implication of their changes so they can reason and act on them. We also know that system design, especially when evolving a system, is often affected by the existing architecture and how the system actually behaves in runtime. This is more than code design, it is often about runtime and operational properties of the system being built or improved, e.g. performance or security properties. Some design decisions also affect how the process will be built, observed and run.
This notion of evolutionary architecture isn’t new, but making it mechanized is even more important when machines are what determines the next iteration of the system architecture. It’s a way for LLM-driven agents to perceive the system they operate on.

Most of the puzzle pieces are already in place.
We have pretty good coding agents that can index and reason about existing code. We already see the beginning of existing technical specification agents. At this point they are interactive (human-in-the-loop). But given enough accurate context, I believe there’s a clear trajectory for agents like this being more independent. Deployment is essentially CI/CD, augmented with some quality controls (testing, code reviews, linting, documentation, etc.). And depending on the desired fitness functions, we can probably implement most with existing observability tools and APIs.

What emerges is what I call an Autonomous Software Development Lifecycle. A system where design choices, specifications and implementations are done by agents that exchange structured artifacts and feed into one another, with very little human intervention. Humans are part of the game in two main aspects: defining the expected system behavior, and tuning the system behavior through some well defined interfaces, notably the definition of the non-functional requirements.

Supervision can also be autonomous. There’s no reason AI agents can’t be connected to existing observability tools, and actively respond to them. Given enough accurate data a capable LLM should be able to derive a decent fix for problems that come up. Combined with existing methodologies of blue/green deployment, redundancy, etc. we effectively get a self healing system.

Taking it a step further, we can consider a scenario where such a system, a collection of agents, also proactively improves the system – a self improving system. An example for this would be a situation where a new technology becomes available and allows for a better implementation of existing functionality. For example, a faster DB, or a better VM that allows doing more work with less network calls.

These last two points about agents being proactive presents a shift from how we operate today with coding agents. Most of the coding agents today are reactive to our requests. Having agents that respond to a changing environment, not us, and acting on it, presents a proactive system that autonomously improves the system. We’re already seeing this at the coding level in some cases. But is there a fundamental barrier to doing this at the system level given that enough accurate context is provided?

Really?

I realize the vision I present here is utopian in a lot of ways and may in fact appear unrealistic. We’re not there yet. There are technical limitations and cost is an issue³. And at this point in time LLMs are not yet reliable enough to “own” a system in production in such a way. Generally speaking there are non-trivial challenges to solve here.
But I do believe we’re starting to see these patterns emerge, and this is a reasonable extrapolation of current advancements in LLMs and the surrounding ecosystem when applied to software development. Especially when it’s integrated with existing observability, software engineering, project management and other relevant tools of the trade.

It’s also interesting to see how this vision is not unique to software development. In a recent interview Satya Nadella was asked (among a lot of other things) about his vision of using models in Microsoft⁴. And it’s interesting to see how he outlines a future where MS-Office apps, Excel in his example, are used autonomously by AI agents. The gist of the tool is not a UI the model works with, it’s the underlying functionality (“logic”) the model integrates with. The focus in that conversation is on the business implications of this kind of development, which I won’t dive into here. But this idea resonated with me when thinking about coding and software engineering and operation in general. The human-centric UX of the tool becomes secondary when AI is involved, but the tool’s functionality can still be available and relevant to AI agents to use. When more and more software engineering tools become available to AI to use, the integration seems inevitable.

We’re training and focusing AI on using the tools we know and use for the tasks we need. The tools that were built for us. The emphasis we’re currently putting on code quality is mostly driven by human involvement in the code. When humans need to read and review the code, we judge and build the coding agents in a way that emphasizes code metrics and quality that are (rightfully) important for humans. But if you take the human interface – the programming language – out of the coding loop, we can probably relax some of these requirements. And let agents use tools that do coding, even if it’s not optimal for human consumption. Instead, we should give agents the tools to perceive and assess its results based on what actually matters – the runtime behavior of the system.

In all likelihood, we’ll get there in small steps, and it will be realized in stages, with different parts of the puzzle implemented by different teams at different times. Even if we assume all pieces are integrated, I still believe we’ll always have the ability to adopt it partially. We’ll probably also see a reality where different teams adopt varying levels of such capabilities. Similar to how today different software development teams adopt different languages and tools, depending on the type of software they use. Some types of software are still better off developed in Assembly or C. In other cases, teams abandon the use of ORM frameworks, even though they can make their coding life easier. It’s quite possible we’ll see teams still doing investigations or carefully feeding planning and coding agents with hand-curated context and tools. But there is a potential here to achieve an order of magnitude more efficiency if we are willing to let go of some control.

What Do We Need To Get There?

As I wrote above, I don’t think we’re there yet.
We’d obviously need to standardize the way agents communicate. Given the amount of available formats and notations for expressing practically anything in software, the challenge will be more about agreeing on the notation rather than inventing one (though that’s always an option).

The challenge may lie not in having a communication format, but in having an efficient one. We’re already seeing examples of this (here, here).

Standardizing on protocols and notation is the easier problem. Agents will need to communicate with one another using semantics of different activities in the SDLC. How projects are organized, how a plan is built, and how it translates to components of the running system. Luckily, decades of humans building software are already built-in to the LLMs through their training. Mapping some of the ideas may be sometimes a challenge, though it seems LLMs can bridge this gap⁵. Mapping semantics between tools seems to be the easier problem. Combining the various domains of a whole project may be a bit more challenging. Bridging the gap between project planning, product roadmap and technical planning/constraints is usually done in the minds of people, and in discussions. Adapting LLMs to do this is, I think, achievable, though not generally trivial⁶.

Of course, having the technical protocols, and ways to encode semantics doesn’t mean we can do it efficiently at scale. So adapting these to be used by LLMs efficiently is of course key to realizing it.

So What’s Left For Humans?

Obviously humans are still left to define requirements and priorities. Current SDD tools don’t seem to address this fully, at least not yet. But there are already attempts to show how such a process can look. It’s clear that there’s still a way to go for automatically translating software requirements to technical specifications. Still, the foundations are there, and one can imagine how this process is realized. I also don’t see LLMs weighing in on business constraints and trade-offs. Taking into consideration social circumstances and constraints is, well, human.

Even when looking at the pure engineering side of things, I expect that humans are still needed, but not so much for their ability to express business application logic in code as much as their ability to reason about system behavior⁷. The future software engineer will need to understand systems engineering at a very fundamental level, and be able to translate it into specification and requirements to be worked on by AI agents. For example, understanding what causes the application to suddenly slow down when a certain event hits, or spot a sporadic race condition that happens because of the distributed nature of the system. Experienced software engineers are able to spot issues like that, especially in a system they know, from just a cursory look at the UI or logs. Systems thinking and understanding will probably become much more important and sought after skill.

In practice, it will probably mean that software engineers will be much more troubled with defining and regulating the “fitness functions” than whether a given snippet of code is readable or violates DRY principles. It could be about modifying the specifications, but also about having a “widgets and knobs” dashboard-like experience where different properties are exposed, allowing engineers to tune and configure the system according to their understanding.

Even if such a system (or ecosystem) of agents materializes, I expect brownfield projects will take time to adapt to such a methodology. There will need to be a lot of work for feeding and adapting existing artifacts (code, documents, specifications) to reverse engineer the implicit knowledge that is often assumed or communicated verbally.

Another place where I believe there’s not yet a replacement for humans is in innovation. New technologies, that could potentially change how we interact with computers or build systems, will most probably require us to train LLM models in how to program and use these. Think of new hardware, applied mathematics or new algorithms. These are all examples, where new application and technical patterns are formed, and these still need to be taught to LLMs⁸.
Similarly, integrating across modalities, or interactions with the physical world will probably require more guidance.

Good engineering – understanding how a system fundamentally works and how it can/should change – will not be replaceable so easily by LLMs. The more we encode it into descriptions, the more we can get done. But these are, at the end of the day, textual probabilistic models. Training on larger datasets will help, but not replace understanding.
It’s the way we build and modify these systems that will change. It is about letting some of the obvious repeating patterns sort themselves out.

Is This Necessarily a Good Thing?

Beyond the technical challenges of realizing this vision, I think it’s important also to ask ourselves whether this kind of state of affairs is a good thing – will this lead to greater success in software delivery, without compromising on quality and safety?
This is not about avoiding it⁹, but rather about articulating the necessary constraints or guardrails so we can avoid a “less than ideal”¹⁰ outcome.

A reality where software is created and modified with zero friction can quickly become risky, especially with mission critical systems. Friction-inducing mechanisms, e.g. compliance and risk assessment, exist for a reason. Software production is not different, especially as software is already a critical component of our modern life. If we do reach a point where software is created autonomously by LLM-driven agents, any human intervention is essentially such a friction. Today, we usually experience this friction as a hindrance to efficient and effective delivery. But in a world where most of the human inefficiencies are taken out of the equation, this friction¹¹ of human intervention may actually work to hedge some (all?) of the risks.

So we need to ask ourselves where human involvement is in fact a positive thing, and where this interacts with the SDLC. I believe that as a rule of thumb, decisions that impact humans should be taken by humans. For example, defining who has access to what piece of data is essentially a human decision directly affecting humans; similarly, how long to keep transaction data has legal and social implications. Contrast this with the decision of whether to use a linked list or a simple array, or how to decompose a system into separate services – these may affect how the system performs, or how long it takes to make changes, but it does not directly affect the human experience, and can be more easily relegated to AI-agents.

This autonomous SDLC has to have some “human-friction” built into it, if only for the sake of safety if not for better results. The exact mechanisms are yet to be seen, but they should be there.

So yes, mechanizing the software development life cycle is an overall good thing to efficiency, and has the potential to alleviate a lot of the problems plaguing the software industry. As a corollary, it can also induce a wave of innovation if software is easier and cheaper to create¹². But we also need to make sure we’re not giving up on human common sense, intuition and ability to innovate. We have to be conscious of what software is getting built, and how it affects us, especially when it evolves more easily.

Let the agents rise!
(but keep an eye on what they’re doing)

And we can argue whether it’s really important given how detached it becomes from humans; e.g. is readability by humans that critical? ↩︎
Or however we’d like to call this role ↩︎
Though I believe it could be offset by the savings in development and down times ↩︎
This actually wasn’t the exact question, but this is roughly where he went with it ↩︎
And more formal semantics may prove useful. ↩︎
And we should consider – should we solve it in a general manner? What if we start by doing it only for web applications? or mobile applications? ↩︎
Remember the point about System ≠ Software, here. ↩︎
Though world models may prove to be different here, but admittedly I’m not an expert. ↩︎
Not trying to be a Luddite. ↩︎
And I will let the dystopian genre experts suggest what is “less than ideal”. ↩︎
Should I say “efficiency-dampening factor”? ↩︎
But note – not necessarily easier to operate. ↩︎

From Code Monkeys to Thought Partners: LLMs and the End of Software Engineering Busywork

When it comes to AI and programming, vibe coding is all the rage these days. I’ve tried it, to an extent, and commented about it at length. While it seems a lot of people believe this to be a game changer when it comes to SW development, it seems that among experienced SW engineers, there’s a growing realization that this is not a panacea. In some cases I’ve even seen resentment or scorn at the idea that vibe coding is anything more than a passing hype.

I personally don’t think it’s just a hype. It might be more in the zeitgeist at the moment, but it won’t go away. I believe that, simply because it’s not a new trend. Vibe coding, in my opinion, is nothing more than an evolution of low/no-code platforms. We’ve seen this type of tools since MS-Access and Visual Basic back in the 90s. It definitely has its niche, a viable one, but it’s not something that will eradicate the SW development profession.

I do think that AI will most definitely change how developers work and how programming looks like. But this still will not make programmers obsolete.

This is because the actual challenges are elsewhere.

The Real bottlenecks in Software Engineering

In fact, I think we’re scratching the surface here. Partially because the technology and tooling are still evolving. But also, it’s because it seems most people¹ looking at improving software engineering are looking at the wrong problem.

Anyone who’s been at this business professionally has realized at some point that code production is not the real bottleneck when it comes to being a productive software engineer. It never was the productivity bottleneck.

The real challenges, in real world software development, especially at scale, are different. They revolve mainly around producing a coherent software by a lot of people that need to interact with one another:

Conquering complexity: understanding the business and translating it into working code. Understanding large code bases.
Communication overhead: the amount of coordination that needs to happen between different teams when trying to coordinate design choices². We often end up with knowledge silos.
Maintaining consistency: using the same tools, practices and patterns so operation and evolution will be easier. This is especially true at a large scale of organization, and over time.
Hard to analyze impacts of changes. Tracing back decisions isn’t easy.

A lot of the energy and money invested in doing day-to-day professional software development is about managing this complexity and delivering software at a consistent (increasing?) pace, with acceptable quality. It’s no surprise there’s a whole ecosystem of methodologies, techniques and tools dedicated to alleviate some of these issues. Some are successful, some not so much.

Code generation isn’t really the hard part. That’s probably the easiest part of the story. Having a tool that does it slightly faster³ is great, and it’s helpful, but this doesn’t solve the hard challenges.
We should realize that code generation, however elaborate, is not the entire story. It’s also about understanding the user’s request, constraints and existing code.

The point here isn’t about the fantastic innovations made in the technology. My point is rather that it’s applied to the least interesting problem. As great as the technology and tooling is, and they are great, simply generating code doesn’t solve a big challenge.

This leads me to thinking: is this it?
Is all the promise of AI, when it comes to my line of work, is typing the characters I tell it faster?
Don’t get me wrong, it’s nice to have someone else do the typing⁴, but this seems somewhat underwhelming. It certainly isn’t a game changer.

Intuitively, this doesn’t seem right. But for this we need to go a step back and consider LLMs again.

LLM Strengths Beyond Code Generation

Large Language Models, as the name implies, are pretty good at understanding, well – language. They’re really good at parsing and producing texts, at “understanding” it. I’m avoiding the philosophical debate on the nature of understanding⁵, but I think it’s pretty clear at this point that when it comes to natural language understanding, LLMs provide a very clear advantage.

And this is where it gets interesting. Because when we look at the real world challenges listed above, most of them boil down to communication and understanding of language and semantics.

LLMs are good at:

Natural language understanding – identifying concepts in written text.
Information synthesis – connecting disparate sources.
Pattern recognition
Summarization
Structured data generation

And when you consider mechanizing these capabilities, like LLMs do, you should be able to see the doors this opens.

These capabilities map pretty well to the problems we have in large scale software engineering. Take, for example, pattern recognition. This should help with mastering complexity, especially when complexity is expressed in human language⁶.

Another example might be in addressing communication overhead. It can be greatly reduced when the communication artifacts are generated by agents armed with LLMs. Think about drafting decisions, specifications, summarizing notes and combining them into concrete design artifacts and project plans.
It’s also easier to maintain consistency in design and code, when you have a tireless machine that does the planning and produces the code based on examples and design artifacts it sees in the system.

It should also be easier to understand the impact of changes when you have a machine that traces and connects the decisions to concrete artifacts and components. A machine that checks changes in code isn’t new (you probably know it as “a compiler” or “static code analyzer”). But one that understands high level design documents and connects it eventually to the running code, with no extra metadata, is a novelty. Think about an agent that understands your logs, and your ADRs to find bottlenecks or brainstorm potential improvements.

And this is where it starts to get interesting.

It’s interesting because this is where mechanizing processes starts to pay off – when we address the scale of the process and volume of work. And we do it with little to no loss of quality.

If we can get LLMs to do a lot of the heavy lifting when it comes to identifying correlations, understanding concepts and communicating about it, with other humans and other LLMs, then scaling it is a matter of cost⁷. And if we manage this, we should be on the road to, I believe, an order of magnitude improvement.

So where does that leave us?

Augmenting SW Engineering Teams with LLMs

You have your existing artifacts – your meeting notes, design specifications, code base, language and framework documentation, past design decisions, API descriptors , data schemas, etc.
These are mostly written in English or some other known format.

Imagine a set of LLM-based software agents that connect to these artifacts, understand the concepts and patterns, make the connections and start operating on them. This has an immediate potential to save human time by generating artifacts (not just code), but also make a lot of the communication more consistent. It also has the potential to highlight inconsistencies that would otherwise go unnoticed.

Consider, for example, an ADR assistant that takes in a set of meeting notes, some product requirements document(s) and past decisions, and identifies the new decisions taken automatically, and generates succinct and focused new ADRs based on decisions reached.

Another example would be an agent that can act as a sounding board to design thinking – you throw your ideas at it, allow it to access existing project and system context as well as industry standards and documentation. You then chat with it about where best practices are best applied, and where are the risks in given design alternatives. Design review suddenly becomes more streamlined when you can simply ask the LLM to bring up issues in the proposed design.

Imagine an agent that systematically builds a knowledge graph of your system as it grows. It does it in the background by scanning code committed and connecting it with higher level documentation and requirements (probably after another agent generated them). Understanding the impact of changes becomes easier when you can access such a semantic knowledge graph of your project. Connect it to a git tool and it can also understand code/documentation changes at a very granular level.

All these examples don’t eliminate the human in the loop. It’s actually a common pattern in agentic systems. I don’t think the human(s) can or should be eliminated from the loop. It’s about empowering human engineers to apply intuition and higher level reasoning. Let the machine do the heavy lifting of producing text and scanning it. And in this case we have a machine that can not only scan the text, but understand higher level concepts, to a degree, in it. Humans immediately benefit from this, simply because humans and machines now communicate in the same natural language, at scale.

We can also take it a step further: we don’t necessarily need a complicated or very structured API to allow these agents to communicate amongst themselves. Since LLMs understand text, a simple markdown with some simple structure (headers, blocks) is a pretty good starting point for an LLM to infer concepts. Combine this with diagram-as-code artifacts and you have another win – LLMs understand these structures as well. All with the same artifacts understandable by humans. There’s no need for extra conversions⁸.

So now we can have LLMs communicating with other LLMs, to produce more general automated workflows. Analyzing requirements, in the context of the existing system and past decisions, becomes easier. Identifying inconsistencies or missing/conflicting requirements can be done by connecting a “requirement analyzer” agent to the available knowledge graph produced and updated by another agent. What-if scenarios are easier to explore in design.

Such agents can also help with producing more viable plans for implementation, especially taking into consideration existing code bases. Leaning on (automatically updated) documentation can probably help with LLM context management – making it more accurate at a lower token cost.

Mechanizing Semantics

We should be careful here not to fall into the trap of assuming this is a simple automation, a sort of a more sophisticated robotic process automation , though that has its value as well.

I think it goes beyond that.
A lot of the work we do on a day to day basis is about bringing context and applying it to the problem or task at hand.

When I get a feature design to be reviewed, I read it, and start asking questions. I try to apply system thinking and first principle thinking. I bring in the context of the system and business I’m already aware of. I try to look at the problem from different angles, and ask a series of “what-if” questions on the design proposed. Sometimes it’s surfacing implicit, potentially harmful, assumptions. Sometimes it’s just connecting the dots with another team’s work. Sometimes it’s bringing up the time my system was hacked by a security consultant 15 years ago (true story). There’s a lot of experience that goes into that. But essentially it’s applying the same questions and thought processes to the concepts presented on paper and/or in code.

With LLMs’ ability to derive concepts, identify patterns in them and with vast embedded knowledge, I believe we can encode a lot of that experience into them. Whether it’s by fine tuning, clever prompting or context building. A lot of these thinking steps can be mechanized. It seems we have a machine that can derive semantics from natural language. We have the potential to leverage this mechanization into the day to day of software production. It’s more than simple pattern identification. It’s about bridging the gap between human expression to formal methods (be it diagrams or code). The gap seems to be becoming smaller by the day.

Let’s not forget that software development is usually a team effort. And when we have little automatic helpers that understand our language, and make connections to existing systems, patterns and vocabulary, they’re also helping us to communicate amongst ourselves. In a world where remote work is prevalent, development teams are often geographically distributed and communicating in a language that is not native to anyone in the development team – having something that summarizes your thoughts, verifying meeting notes against existing patterns and ultimately checking if your components behave nicely with the plans of other teams, all in perfect English, is a definite win.

This probably won’t be an easy thing to do, and will have a lot of nuances (e.g. legacy vs. newer code, different styles of architecture, evolving non functional requirements). But for the first time I feel this is a realistic goal, even if it’s not immediately achievable.

Are We Done?

This of course begs the question – where is the line? If we can encode our experience as developers and architects into the machine, are we really on the path to obsolescence?

My feeling is that no, we are not. At the end of the process, after all alternatives are weighed, assumptions are surfaced, trade offs are considered, a decision needs to be taken.

At the level of code writing, this decision – what code to produce – can probably be taken by an LLM. This is a case where constraints are clearer and with correct context and understanding there’s a good chance of getting it right. The expected output is more easily verifiable.

But this isn’t true for more “strategic” design choices. Things that go beyond code organization or localized algorithm performance. Choices that involve human elements like skill sets and relationships, or contractual and business pressure. Ultimately, the decision involves a degree of intuition. I can’t say whether intuition can be built into LLMs, intuitively I believe it can’t (pun intended). I highly doubt we can emulate that using LLMs, at least not in the foreseeable future.

So when all analysis is done, the decision maker is still a human (or a group of humans). A human that needs to consider the analysis, apply his experience, and decide on a course forward. If the LLM-based assistant is good enough, it can present a good summary and even recommendations, all done automatically. This analysis still needs to be understood and used by humans to reach a conclusion.

Are we there yet? No.
Are we close? Closer than ever probably, but still a way to go.

Can we think of a way to get there? Probably yes.

A Possible Roadmap

How can we realize this?

The answer seems to be, as always, to start simple, integrate and iterate; ad infinitum. In this case, however, the technology is still relatively young, and there’s a lot going on. Anything from the foundation models, relevant databases, coding tools, to prompt engineering, MCPs and beyond . These are all being actively researched and developed. So trying to predict how this will evolve is even harder.

Still, if I have to think on how this will evolve, practically, this is how I think it will go, at least one possible path.

Foundational System Understanding

First, we’ll probably start with simple knowledge building. I expect we’ll first see AI agents that can read code, produce and consume design knowledge – how current systems operate. This is already happening and I expect it will improve. It’s here mainly because the task in this case is well known and tools are here. We can verify results and fine tune the techniques.
Examples of this could be AI agents that produce detailed sequence diagrams of existing code, and then identifying components. Other AI agents can consume design documents/notes and meeting transcriptions, together with the already produced description to produce an accurate record of the changed/enhanced design. Having these agents work continuously and consistently across a large system already provides value.

Connecting Static and Dynamic Knowledge

Given that AI agents have an understanding of the system structure, I can see other AI agents working on dynamic knowledge – analyzing logs, traces and other dynamic data to provide insights into how the system and users actually behave and how the system evolves (through source control). This is more than log and metric analysis. It’s overlaying the information available over a larger knowledge graph of the system, connecting business behavior to the implementation of the system, including its evolution (i.e. git commits and Jira tickets).

Can we now examine and deduce information about better UX design?
Can we provide insights into the decomposition of the system?

Enhanced Contextual Assistant and Design Support

At this point we should have everything to actually provide more proactive design support. I can see AI agents we can chat with, and help us reason about our designs. Where we can suggest a design alternative, and ask the agent to assess it, find hidden complexities, with the context of the existing system. Combined with daily deployments and source control, we can probably expect some time estimates and detailed planning.

This is where I see the “design sounding board” agent coming into play. As well as agents preemptively telling me where expected designs might falter.

More importantly, it’s where AI agents start to make the connections to other teams’ work. Telling me where my designs or expected flow will collide with another team’s plans.
Imagine an AI agent that monitors design decisions, of all teams and domains, identifies the flows they refer to, and highlights potential mismatches between teams or suggests extra integration testing, if necessary, all before sprint planning starts. Impact analysis becomes much easier at this point, not because we can query the available data (though we could, and that’s nice as well), but because we have an AI agent looking at the available data, considering the change, and identifying on its own what the impact is.

There’s still a long way to go until this is realized. Implementing this vision requires taking into account data access issues, LLM and technology evolution, integration and costs. All the makings of a useful software project.
I also expect quite a bit can change, and new techniques/technologies might make this more achievable or completely unnecessary.

And who knows, I could also be completely hallucinating. I heard it’s fashionable these days.

Conclusion: The Real Promise of LLMs in Software Engineering

I’ve argued here that while vibe coding and code generation get most of the attention, they aren’t addressing the real bottlenecks in software development. The true potential of Large Language Models lies in their ability to understand and process natural language, connect disparate information sources, and mechanize semantic understanding at scale.

LLMs can transform software engineering by tackling the actual challenges we face daily: conquering complexity, reducing communication overhead, maintaining consistency, and analyzing the impact of changes. By creating AI agents that can understand requirements, generate documentation, connect design decisions to implementation, and serve as design thinking partners, we can achieve meaningful productivity improvements beyond simply typing code faster, as nifty as that is.

What makes this vision useful and practical is that it doesn’t eliminate humans from the loop. Rather, it augments our capabilities by handling the heavy lifting of information processing and connection-making, while leaving the intuitive, strategic decisions to experienced engineers. This partnership between human intuition and machine-powered semantic understanding represents a genuine step forward in how we build software.

Are we there yet? Not quite. But we’re closer than ever before, and the path forward is becoming clearer.

Have you experienced any of these AI-powered workflows in your own development process? Do you see other applications for LLMs that could address the real bottlenecks in software engineering?

At least most who publicly talk about it ↩︎
‘Just set up an api’ is easier said than done – agreeing on the API is the hard work ↩︎
And this is a bit debatable when you consider non-functional requirements ↩︎
I am getting older ↩︎
Also because I don’t feel qualified to argue on it ↩︎
Data mining has been around forever, but mostly works on structure data ↩︎
Admittedly, not a negligible consideration ↩︎
Though from a pure mechanistic point of view, this might not be the most efficient way ↩︎

Exploring Vibe Coding with AI: My Experiment

1 Reply

In my previous post I mentioned vibe coding as a current trend of coding with AI. But I haven’t actually tried it.

So I’ve decided to jump on the bandwagon and give it a try. Granted, I’m not the obvious target audience for this technique, but before passing judgment I had to see/feel it for myself.

It’s not the first time I generated code using an LLM with some prompting. But this time I was more committed to try out “the vibe”. To be clear, I did not intend to go all in with voice commands, transcription, and watching Netflix while the LLM worked. I did intend to review the code, and keep in touch with the output at every point. I wanted to test the tool’s capabilities while still being very much aware of what was going on.

Below is an account of what happened, my thoughts and conclusions so far.
A general disclaimer is of course in place: I’m still exploring these tools, and it’s quite possible there could be improvements to the process. My experience, however, is very much influenced by my experience as a developer. My choice of tools and how to use them is therefore very much biased towards usage as an experienced developer looking to increase productivity, not a non-coder looking to crank out one-off applications¹.

The Setup

I set out to create a new simple tool for myself (actually to be used at work), something I actually find useful, and is not an obvious side project that’s been done a million times, and therefore less likely (I hope) to be in the LLM’s training data. It’s a project done from scratch, and I’m trying to do something that I don’t have a lot of experience with. It is also meant to be fairly limited in scope.

The project itself is a “Knowledge Graph Visualizer”, essentially an in-browser viewer of a graph representing arbitrary concepts and their relationships. I intended this to be purely browser, JS code. The main feature is a 3D rendering of the graph, allowing navigation through the concepts and their links. You can see the initial bare specification here.

To get a feel for the project, here’s a current screenshot:

KG-Viewer showing its own knowledge graph

With respect to tooling I went with Cursor (I use Cursor Pro), using primarily Claude-Sonnet 3.7 model. The initial code generation was actually done with Gemini 2.5 pro. But I quickly ran out of credits there. So the bulk of the work was done with Cursor.

I did not use any special cursor rules or MCP tools. This may have altered the experience to a degree (though I doubt it), so I will need to continue trying it as I explore these tools and techniques.

Getting Into the Vibe

It actually started fairly impressive. Given the initial spec, Gemini generated 6 files that provided the skeleton for a proof of concept. All of these files are still there. I did not look too deeply into the generated code. Instead, I initialized an empty simple project, launched Cursor, and copied the files there. With a few tweaks², it worked. I had a working POC in about one hour of work. Without ever coding 3D renderings of graphs.

Magic!
I’ll be honest – I was impressed at first. I got a working implementation for drawing a graph with Three.js, for some JSON schema describing a graph. Given that I never laid eyes on Three.js, this was definitely faster than I would have gotten even to this simple POC.

I did peek at the code. I wasn’t overly impressed by it – there was a lot of unnecessary repetition, very long functions, and some weird design choices. For example, having a style.css holding all the style classes, but at the same time generating a new style and dynamically injecting it into the document.
But, adhering to my “viber code”, I did not touch the code, instead working only with prompts.

Then I started asking for more features.

Cursor/Claude, We Have a Problem

A POC is nice. But I actually need a working tool. So I started asking for more features.
Note, I did not just continue to spill out requests in the chat. I followed the common wisdom – using a new chat instance, laying out the feature specification and working step by step on planning and testing before implementation.

I wrote a simple file, which should allow me to trace the feature’s spec and implementation.
The general structure is simple:

- Feature Specification - Plan - Testing - Implementation Log

Where I fill in only the Feature Specification, and let Cursor fill in the plan (after approval) and the “Implementation Log” as we proceed.

The plan was to have a working log of progress, to be used as both a log of the work, but also provide context to future chat sessions.

I don’t intend to re-create here the entire chat session or all my prompts, as this is not intended to be a tutorial on LLM techniques. But fair to say that the first feature (data retrieval), was implemented fairly easily, using only prompts.

Just One Small Change…

I was actually still pretty impressed at this point, so I simply asked for tiny small feature – showing node and link labels. I did it without creating an explicit “feature file”.

The code didn’t work. So I asked Cursor to fix it. And this quickly spiraled out of control. Cursor’s agent of course notified me on every request that it had definitely figured out the issue, and now it has the fix (!).
It didn’t.

I remained loyal to the “vibe coder creed”, and did not try to debug/fix the code myself. Instead deliberately going in cycles of prompting for fixes, accepting changes blindly, testing, and prompting again with new errors.

Somewhere along this cycle, the code changes made by the agent actually created regression in the application’s code resulting in the application not loading at all.

After roughly 3 hours, and a lot more grey hair, I did notice that the Cursor agent was going in circles – simply trying out the same 3 solutions, with no idea what’s wrong. But still confidently hallucinating solutions (“Now I see the issue…”³).

This was so frustrating that at this point I simply took it upon myself to actually look at the code, which was a complete mess. I looked at the problematic code, consulted git diffs to restore basic functionality, and solved the actual issue with about 10 more minutes of Google search.

To be fair, from my very rudimentary google search it seemed my request (link labels) wasn’t that easy to achieve. It’s apparently not that obvious (again, without being an expert on Three.js). I relaxed the requirement a bit, and found a simple solution.
Still, the whole cycle of back and forth of code changes, especially to unrelated code, was very much counter-productive. The vibes were all wrong. Getting back to working code took another 2-3 hours.

At this point I was thinking “oh well, you can’t win them all”. I wanted to turn to something simple. And looking at the state of the code, a simple cleanup should be easy enough, right?

Right? …

Now It’s Just Cleanup

Well … it depends.

I went back into “vibe coding” mode. This time, I defined very basic code cleanup procedures. I then asked Cursor’s agent (in a new session), to go through the source code and follow these steps to clean it up.

It actually did reasonably well for small files. The bigger files proved to be more challenging. Trying to clean them up ended up messing the files completely. For some reason, the LLM agent removed functioning code, and created functionality regressions. Trying to quickly fix them ended up in causing more issues. It was clearly guessing at this point.

Given my battle scars with the previous feature request, I avoided this hallucination death spiral. Instead, I went through git history, found a working version, and restored the working code “by hand” – actully typing in code. I wasn’t a vibe coder anymore, but the application worked, the code was cleaner, and my blood pressure remained fairly low (I think).

The experience felt like trying to mentor a junior developer to code without creating regressions. The problem is it’s a fast and confident junior developer, with short term memory loss, who is apparently so eager to please that he simply spews out code that looks remotely connected to the problem at hand, with little understanding of context; proving to be ignorant even of changes it itself made to the code.

Documentation for Man and Machine

At this point I decided to go back to basics, where LLMs truly shine – understanding and creating text. I asked for it to create documentation for specific flows in the code (init sequence, clicking on a legend item). Unsurprisingly, with a few simple prompts, the agent produced decent documentation for what I asked, including a mermaid.js diagram code.

This is important not simply because it allowed me to document project easily, which is nice. Creating a textual documentation of specific flows also allowed me to provide better context for other chat sessions. And this is an important insight – textual descriptions of the code are useful for humans as well as the LLMs.

Other Features

At this point I turned to develop more features – loading data and “node focus“. In both cases I went back to providing feature files, with specifications, and asking the agent to update the files with plans and implementation logs.

I was a bit more cautious now. I reviewed code more carefully and intervened where I felt the code wasn’t good. In some cases it was obvious the code wasn’t functionally correct, but instead of trying to “fight” with the agent, I accepted the code and went on to change it myself.

A repeating phrase in all my prompts at this point was:

Do minimal code changes. Change only what is needed and nothing more.

This, combined with being more cautious and careful, resulted in pretty good results. I managed to implement two features in a short time. Probably a bit shorter compared to what it would have taken me to run through Three.js tutorials and do it myself.

Final Thoughts

So where does this leave me?

I have a working application. And if I had to learn Three.js from scratch myself, it would have taken me considerably longer to create. It’s working, and it’s useful. This is an important bottom line.

Small Application, Good Starting Point

The initial code, generated by the LLM (Gemini or Claude) does serve as a good starting point, especially in areas or frameworks that are unfamiliar to the developer.

But this is still a far cry from replacing developers. There are tool limitations, some of them, I expect, introduced by Cursor rather than the LLM. These limitations can cause havoc if the agent is left to proceed with no oversight.
And review is harder when there’s a ton of unorganized code⁴.

We can probably make it better with rules, better prompts, and combination of agents. And of course advances in LLM training.

This is a good starting point. But we need to remember this is a very small application, made from scratch. In the real world, a lot of use cases are not that simple at all. The more I read and think about it, this bears a striking resemblance to no-code/low-code tools. Also in those cases, it’s easy to achieve quick results for simple uses cases, but very hard to scale development when features creep in or the application needs to scale.

It’s not that low-code tools don’t have their place. They serve a very specific (viable) niche. But as experience shows, they haven’t replaced developers.

Could this be different?
What would it take to tackle more serious challenges, with “vibe coding”?

Context is King

It’s quite obvious that in the kingdom of tokens, amidst ramparts of code and wind all of chat messages, there is only one king, and its name is Context⁵. As LLMs are limited in their context size, and a lot of it is taken up by wrapping tools (Cursor in this case), context for an LLM chat is an expensive real estate.

So while context windows can get big, we’ll probably never have enough when we get to more complicated tasks and bigger code bases. There’s a preservation of complexity at play.

Accuracy and precision in the context play a crucial role in effectiveness. Context passed to LLMs needs to be information-dense. We should probably start considering how efficient is the context we’re providing to LLMs. I don’t know how to measure context efficiency yet, but I believe this will be important to be more effective as tasks become more complicated.

But there’s more than just the LLM and how to operate it.

You’re Only as Good as Your Tools, Also When Vibing

It’s quite clear that mistakes done by LLMs, and humans, can be avoided/caught with the help of the right tools. Even in my small example described above, cooperation of the LLM agent with external tools (console logs, shell commands) resulted in better understanding and a more independent agent.

I suspect that having more tools, e.g. relevant MCP server for documentation, can significantly help. I expect the integration of LLMs with tools will become more prominent and more necessary to create more independent coding agents.

One often overlooked tool is the simple document explaining the context of the project, specific features and current tasks. When LLMs will work seamlessly with Architecture Decision Records and diagram as code tools, I expect to see better results. The memory bank approach seems to be a step in that direction, though it’s hard to assess how effective it is.

I have noticed in this exercise that supplying the LLM with context of how a flow works currently (e.g. loading the data), allows it to identify the necessary changes more easily.

Diagram as code play a role now not just for humans developers, but also as a way to encode context for the application. There’s a feedback loop here between the LLM generating documentation, and using it as input for further tasks.

Effective Vibing

The real question is about the effectiveness of the vibe coding approach. With what degree of agent independence can we achieve good results.

I’m not sure how to assess this. One approximation of this might be the rate of bugs to user chat messages times lines generated in a given vibe coding session. But there are obviously other parameters involved⁶.

It will be interesting to measure this over time, with more integrated tools, improved LLMs and possibly improved tools.

I’m not sure how this will evolve over time. I do think, however, that if LLMs with coding tools will be reduced to a glorified low-code platform it will be a miss for software engineering in general. The technology seems to be more powerful than that, since it has the potential to more easily bridge the gap between human language and rigorous computer programs; and do it in both directions.

On to explore more.

Not that there’s anything wrong with that ↩︎
Yep, I asked Cursor to keep track of the changes at this point ↩︎
A phrase which, I guess, is close to becoming a meme onto itself ↩︎
But then again, not sure it’s a problem in the long run ↩︎
Always looking for opportunities to paraphrase one of my favorite book series; couldn’t resist this one ↩︎
And we should be careful of Goodhart’s law. ↩︎

AI and the Nature of Programming – Some Thoughts

3 Replies

So, AI.
It’s all the rage these days. And apparently for good reason.

Of course, my curiosity, along with a fair amount of FOMO¹ leads me to experimenting and learning the technology. There’s no shortage of tutorials, tools and models. A true Cambrian explosion of technology.
This also aligns fairly easily with my long time interests of development tools, development models, and software engineering in general. So there’s no shortage of motivation to dive into this from a developer’s perspective².

And the debate is on, especially when it comes to development tools.

It’s no secret that tools powered by large language models (LLMs), like Github Copilot, Cursor, and Windsurf³, are becoming indispensable. Developers all over adopt them as an essential part of their daily toolset. They offer the ability to generate code snippets, debug errors and refactor code with remarkable speed. This shift has sparked a fascinating debate about the role of AI in coding. Is it merely a productivity booster? Or does it represent a fundamental change in how we think about programming itself?

At its core, coding with AI promises to make software development faster and arguably more accessible. For simple, well-defined tasks, AI can produce functional code in seconds. This reduces the cognitive load on developers and allows them to focus on higher-level problem-solving. But software development in the wild, especially for ongoing product development, becomes very complicated very quickly. As complexity grows, the limitations of AI-generated code become obvious. While LLMs can produce code quickly and easily, the quality of its output often depends on the developer’s ability to guide and refine it.

So while AI excels at speeding up simple tasks, there are still challenges with more complex tasks. And there are implications to the ability to maintain code over time. But, I cannot deny we’re apparently at the beginning of a new era. And this raises the question of whether traditional notions of “good code” still apply in an era where AI might take over the bulk of maintenance work.

And I ask myself (and you): can we imagine a future where AI no longer generates textual code? Instead, it operates on some other canonical representation of logic. Are we witnessing a shift in the very nature of programming?

Efficiency of AI in Coding

Before diving into the hard(er) questions, let’s take a step back.

One of the most compelling advantages of coding with AI is its ability to significantly speed up the development process. This is especially true for simple and focused tasks. AI-powered tools, like GitHub Copilot and ChatGPT, excel at generating boilerplate code, writing repetitive functions, and even suggesting entire algorithms based on natural language prompts. For example, a developer can describe a task like “create a function to sort a list of integers in Python,” and the AI will instantly produce a working implementation. This capability not only saves time. It also reduces the cognitive burden on developers⁴. Consequently, developers can focus on more complex and creative aspects of their work.

The efficiency of AI in coding is particularly evident in tasks that are well-defined and require minimal context. Writing unit tests, implementing standard algorithms, or formatting data are all areas where AI can outperform human developers in terms of speed. AI tools can also quickly adapt to different programming languages and frameworks, making them versatile assistants for developers working in diverse environments. For instance, a developer switching from Python to JavaScript can rely on AI to generate syntactically correct code in the new language, reducing the learning curve and accelerating productivity. I often use LLMs to create simple scripts quickly instead of consulting documentation on some forgotten shell scripting syntax.

AI’s effectiveness in coding often depends on the developer’s ability to simplify tasks. The developer should break down larger, more complex tasks into smaller, manageable components. AI thrives on clarity and specificity; the more focused the task, the better the results. Yes, we have thinking models now, and they are becoming better every day. Still, they require supervision and accurate context. Contexts are large, and they’re not cheap.

At this point in time, developers still need to break down complicated tasks into more manageable sub tasks to be successful. This is often compared to a senior developer/tech lead detailing a list of tasks for a junior developer. I often find myself describing a feature to an LLM, asking for a list of tasks before coding, and then iterating over it together with the LLM. This works quite well in small focused applications. It becomes significantly more complicated with larger codebases.

While AI excels at handling simple and well-defined tasks, its performance tends to diminish as the complexity of the task increases. This is not necessarily a limitation of the AI itself but rather a reflection of the inherent challenges in translating high-level, ambiguous requirements into precise, functional code. For example, asking an AI to “build a recommendation system for an e-commerce platform” is a very complex task. In contrast, requesting a specific algorithm, like “implement a collaborative filtering model”, is simpler. The former requires a deep understanding of the problem domain, user behavior, and system architecture. These are areas where AI still struggles without significant human guidance.

As it stands today, LLMs act as a force multiplier for developers, enabling them to achieve more in less time. The true potential is realized when developers approach AI as a collaborative tool rather than a fully autonomous coder.

The “hands-off” approach (aka “Vibe coding“), where developers rely heavily on AI to generate code with minimal oversight, often leads to mixed results. AI can produce code that appears correct at first glance. Yet, it can contain subtle bugs, inefficiencies, or design flaws that are not immediately obvious. This is just one case I came across, but there are a lot more of course.

It’s not just about speed

But it’s more than simple planning, prompt engineering and context building. AI can correct its own errors, autonomously.

One of the most impressive features of AI in coding is its ability to detect and fix errors. When an LLM generates code, it doesn’t always get everything right the first time. Syntax errors, compilation issues, or logical mistakes can creep in. Yet, modern AI tools are increasingly equipped to spot these problems and even suggest fixes. For instance, tools like Cursor’s “agent mode” can recognize compilation errors. These tools then automatically try to correct them. This creates a powerful feedback loop where the AI not only writes code but also improves it in real time.

But it’s important to note here that there’s a collaboration here between AI and traditional tooling. Compilers make sure that the code is syntactically correct and can run, while LLMs help refine it. Together, they form a system where errors are caught early and often, leading to more reliable code. I have also had several cases where I asked the LLM to make sure all tests pass and there are no regressions. It ran all tests and fixed the code based on broken tests.
That is, without human intervention in that loop.

So AI, along with traditional tools (compilers, tests, linters) can be autonomous, at least to a degree.

It’s not just about correct code

As we all know, producing working code is only one (important) step when working as an engineer. It’s only the beginning of the journey. This is especially true when working on ongoing product development. It is probably less so in time-scoped projects. In ongoing projects, development never really stops. It continues unless the product is discontinued. There are mountains of tools, methodologies and techniques dedicated to maintain and evolve code over time and at scale. It is often a much tougher challenge compared to the initial code generation.

One of the biggest criticisms of AI-generated code is that it often lacks maintainability. Maintainable code is code that is easy to read, understand, and change over time. Humans value this because it makes collaboration and long-term project evolution easier. Yet, AI doesn’t always prioritize these qualities. For example, it might generate long, convoluted functions or introduce unnecessary methods that make the code harder to follow.

The reality is that code produced by an LLM, while often functional, may not always align with human standards of readability and maintainability.
I stopped counting the times I’ve had some LLM produce running, and often functionally correct code, that was horrible in almost every aspect of clean and robust code. I dare say a lot of the code produced is the antithesis of clean code. And yes, we can use system prompts and rules to facilitate better code. However, it’s not there yet, at least not consistently. This issue is not necessarily a fault of AI itself. It reflects the difficulty in defining and agreeing on what constitutes “good code”.

Whether or not LLMs get to the point where they can produce more maintainable code is uncertain. I’m sure it can improve, and we haven’t seen the end of it yet. I wonder if that is a goal we should be aiming for in the first place. We want “good” code, because we are there to read it, and work with it after the AI has created it.

But what if that wasn’t the case?

A code for the machine, by the machine

LLMs are good at understanding our text, and eventually acting on it – producing the text that will answer our questions/instructions. And when it comes to code, it produces code, as text. But that text is for us – humans – to consume. So we review and judge through this lens – code that we need to understand and work with.

We do it with the power of our understanding, but also with the tools that we’ve built to help us do it – compilers, linters, etc. It’s important to note that language compilers are tools for humans to interact with the machine. It’s a tool that’s necessary when dealing with humans instructing the machine (=writing code). The software development process, even with AI, requires it because the LLM is writing code for humans to understand. It also allows us to leverage existing investments in programming.

But when an LLM is generating code for another LLM to review, and when it iterates on the generated response, the code doesn’t need to be worked on by humans. Do we really need the code to be maintainable and clear for us?
Do we care about duplication of code? Meaningful variable and class names? Is encapsulation important?
LLMs can structure their output, and consume structured inputs. Assuming LLMs don’t hallucinate as much than I’m not sure type checking is that impactful as well.

I think we should not care so much about these things.
At the current rate of development around LLMs there’s no reason we shouldn’t get to a point where LLMs will be able to analyze an existing code base and modify/evolve it successfully without a human ever laying eyes on the code. It might require some fancy prompting or combination of multiple LLM agents, but we’re not so far.

Another force at play here, I believe, is that code can be made simpler and straightforward if it doesn’t need to abstract away much of the underlying concepts. A lot of the existing abstractions are there because of humans. Take for example UI frameworks, or different SDKs, component frameworks and application servers. Most of the focus there is about abstracting concepts and letting humans operate at a higher level of understanding. It can be leveraged by LLMs, but it doesn’t necessarily have to be. Do I need an ORM framework when the LLM simply produces the right queries whenever it needs to?
Do I need middleware and abstractions over messaging when an AI agent can simply produce the code it needs, and replicate it whenever it needs to?

My point is, a lot of the (good) concepts and tools and frameworks we created in programming are good and useful under the assumption that humans are in the loop. Once you take humans out of the loop, are they needed? I’m not so sure.

The AI “Compiler”

Let’s take it a step further.
Programming languages are in essence a way for humans to connect with the machine. It has been this way since the early days of assembly language. And with time, the level of expression and ergonomics of programming languages have evolved to accommodate humans working with computers. This is great and important, because we humans need to program these damn computers. The easier it is for us, the more we can do.

But it’s different when it’s not a human instructing the machine. It’s an AI that understands the human, but then translates it to something else. And another AI works to evolve this output further. Does the output need to be understandable by humans?
What if LLMs understand the intent given by us, but then continue to iterate over the resulting program using some internal representation that’s more efficient?

Internal representations are nothing new in the world of compilers. Compiler developers program them to enable various operations that compilers often perform. Operations like optimizations, type checking, tool support, and generating outputs.
Why can’t LLMs communicate over code using their own internal representation, resulting in much more efficient operation and lower costs?
This is not just for generating a one-time binary, but also for evolving and extending the program. As we observed above, software engineering is more than a simple generation of code.
It doesn’t have to be something fancy or with too many abstractions. It needs to allow another LLM/AI to work and continue to evolve it whenever a new feature specification or bug is found/reported.
Do we really need AI to produce a beautiful programming language, mimicking some form of structured English, when there’s no English reader who’s going to read and work on it?

Why not have AI agents produce something like “textual/binary Gibberlink” an AI-oriented “bytecode” when producing our programs:

Is the human to machine connection through a programming language necessary when we have a tool that understands our natural language well enough, and can then reason on its own outputs?

LLMs can already encode their output in structured formats (e.g. JSON) that are machine processable. Is it that big of a leap to assume they’d be able to simply continue communicating with themselves and get the job done based on our specifications, without involving us in the middle?

Vibe coding is apparently a thing now. I don’t believe it’s a sustainable trend⁵. But the main reason is that it focuses on a specific point in the software life cycle – the point of generating code.
What if we can take it to the extreme? What if we remove the human from the coding process throughout the software life cycle?

I can’t really predict where this is going. At this point I don’t know the technology well enough to guesstimate, and I’m no oracle. But I do see this as one possible direction with a definite upside. And it’s definitely interesting to follow.

If programming is machines talking to machines, maintainability and evolution of code becomes a different game.

“Code” becomes a different game.

Is programming dead?

What would such a future hold for the programming professionals?

Again, I’m not great at making prophecies. But the way I see it, and looking at history, I don’t belong to the pessimistic camp. So in my opinion – no, I don’t subscribe to the notion that programming is dead.

History has taught us an important lesson. Creating software with more expressive power did not decrease the amount of software created. A higher level of abstraction did not lessen software production either. Quite the contrary. More tools, and being capable of working at higher levels of abstraction meant that more software is created. Demand grew as well. It’s just the developers that needed to adapt to the new tools and concepts. And we did⁶.

Demand for software still exists, and it doesn’t look like it’s receding. I believe that developers who will adapt to this new reality will still be in demand as well.

I expect LLMs will improve, even significantly, in the foreseeable future. But this doesn’t mean there’s no need for software developers. I expect software development tasks to become more complex. As developers free their time and minds from the gritty details of sorting algorithms, database schemas and implementing authentication schemes, they will focus on bigger, more complicated tasks. So software development doesn’t become less complicated, we’re just capable of doing more stuff. Complexity is simply moving to other (higher level?) places⁷.

Could it be that software architects will become the new software engineers?
Are all of us going to be “agent coders”?

I really don’t know, but I intend to stick around and find out.

Where do you think this is going?

And, admittedly, fear of becoming irrelevant ↩︎
And yes, AI was used when authoring this post, a bit. But no LLM was harmed, that I know of ↩︎
Originally I intended to add more examples, but realized that by the time I finish writing a list, at least 3 new tools will be announced. So… [insert your favorite AI dev tool here] ↩︎
Give or take hallucinations ↩︎
Remember no-code? ↩︎
I’m old enough to have programmed in Java with no build tool, even before Ant. Classpath/JAR hell was a very real thing for me. ↩︎
“The law of complexity preservation in software development”? ↩︎

Adding Bots to a Simple Game

Leave a reply

We have previously seen how we can create a fairly simple game in a short amount of time. In the closing post of the series, I mentioned one possible direction for evolving the code was adding the option to “play against the computer”, i.e. have the option for an automated player, or even two.

This is not only interesting from the coding point of view. It also allows us to explore how to code heuristics and/or “AI” into the game, compare strategies, etc.

In this post, I will describe the necessary changes made in the code in order to incorporate these bots into the game. This is not meant to be anyway authoritative source on how to write good AI for games, or how to implement it efficiently. It’s just one way to add this kind of feature.

If you want to see the end result, have a look at the deployed game instance, and follow the instructions for specifying automated players.

Enabling Automated Players

The first order of business is to facilitate introduction of AI players (“bots”). So far, the code we built was responding to mouse clicks in the browser, in other words, driven by human interaction. We’d like to allow for moves to be decided by code, and for the game to invoke such code and proceed with the game, without any human interaction.

Keeping to the spirit of the original design, we’re still building the automated players as part of the Javascript, browser-based code. We don’t want to introduce another separate runtime component to the system.

So the next two commits (6a4c509, 5489462) introduce this facility:

	const PLAYER = {
	one : {
	toString : () => "ONE"
	, theOtherOne : () => PLAYER.two
	, number : 1
	, ai : () => PLAYER.one._aiPlayer
	, _aiPlayer : None

	}
	, two : {
	toString : () => "TWO"
	, theOtherOne : () => PLAYER.one
	, number : 2
	, ai : () => PLAYER.two._aiPlayer
	, _aiPlayer : None
	}
	}

	class MancalaGame
	{
	constructor(gameSize,cnvsELID,_updatePlayerCallback,_showMsgCallback,requestedAIPlayers)
	{
	…
	this._setupAIPlayersIfRequested(requestedAIPlayers);
	…
	}

	_setupAIPlayersIfRequested(requestedAIPlayers)
	{
	dbg("Setting AI Players…");
	PLAYER.one._aiPlayer = maybe(determineAIPlayer(requestedAIPlayers.p1))
	PLAYER.two._aiPlayer = maybe(determineAIPlayer(requestedAIPlayers.p2))

	dbg("AI Players: P1: " + PLAYER.one._aiPlayer + ", P2: " + PLAYER.two._aiPlayer);

	function determineAIPlayer(requestedAI)
	{
	return requestedAI ? new SimpleAIPlayer() : null;
	}
	}

	start()
	{
	this._makeNextMoveIfCurrentPlayerIsAI();
	}

	handleCellClick(boardCell)
	{
	…
	this._makeNextMoveIfCurrentPlayerIsAI()
	}

	_makeNextMoveIfCurrentPlayerIsAI()
	{
	if (!this.gameDone)
	{
	this.player.ai().ifPresent(aiPlayer => {
	let aiMove = aiPlayer.nextMove(this.board,this.player.number)
	setTimeout(() => { this._makeMove(aiMove)}, 200) //artifical wait, so we can "see" the ai playing
	})
	}
	}
	}

view raw game.js hosted with ❤ by GitHub

	const P2_PARAM_NAME = "p2";
	const P1_PARAM_NAME = "p1";

	function setup()
	{
	game = new main.MancalaGame(resolveGameSize(),'cnvsMain',updateCurrentPlayer,showMsg, resolveRequestedAI());
	game.start();
	}

	function resolveRequestedAI()
	{
	let params = new URLSearchParams(window.location.search);
	let p2 = params.has(P2_PARAM_NAME) ? params.get(P2_PARAM_NAME) : "";
	let p1 = params.has(P1_PARAM_NAME) ? params.get(P1_PARAM_NAME) : "";
	return { p1 : p1, p2 : p2}
	}

view raw index.html hosted with ❤ by GitHub

	class SimpleAIPlayer
	{
	constructor()
	{

	}

	/**
	* Given a board and side to play, return the cell to play
	* @param {Board} board The current board to play
	* @param {number} side The side to player, either 1 or 2
	*
	* @returns The board cell to play
	*/
	nextMove(board,side)
	{
	requires(board != null, "Board can't be null for calculating next move")
	requires(side == 1 \|\| side == 2,"Side must be either 1 or 2")

	//Simple heuristic: choose the cell with the largest number of stones.
	var maxStoneCell = side == 1 ? 1 : board.totalCellCount()-1;
	switch (side)
	{
	case 1 : board.forAllPlayer1Cells(c => { if (board.stonesIn(c) > board.stonesIn(maxStoneCell)) maxStoneCell = c })
	case 2 : board.forAllPlayer2Cells(c => { if (board.stonesIn(c) > board.stonesIn(maxStoneCell)) maxStoneCell = c })
	}
	dbg("Playing cell: " + maxStoneCell + " with " + board.stonesIn(maxStoneCell) + " for player " + side);
	return maxStoneCell;
	}
	}

	module.exports = {
	SimpleAIPlayer
	}

view raw SimpleAIPlayer.js hosted with ❤ by GitHub

Mancala Bots

You can see that the setup of the AI players is done during the construction of the MancalaGame class (game.js, line 24). The requested AI player type is passed using URL parameters (index.html, lines 6,10-16) which are then parsed and used for initializing the bots. Note that the necessary player class is setup in the global PLAYER objects¹. At this point we have only one type of player – SimpleAIPlayer.

The invocation of the AI player happens when responding to the player’s click (game.js, line 50). The _makeNextMoveIfCurrentPlayerIsAI function (game.js lines 53-62) simply checks that the game isn’t done, and whether the current player is an AI one. If it is, we invoke the nextMove function which is the main function in the AI player’s interface. The result of this function is simply the cell to play. The function then invokes the makeMove function, which is also used for human players from the UI.

Another small addition is the start function for the MancalaGame class (game.js, lines 42-45). Which simply tests if player one (the current player at the beginning of the game), is an AI, and makes a move. This is used to kickstart a game where the first player is a bot. The 2nd player being a bot, and further moves of the 1st player, is handled through the mechanism described above.

We Start Simple

The first implementation of a bot in this game (SimpleAIPlayer.js) is dead simple – it’s based on a very naïve heuristic: play the cell with the most cells in it. To be honest, it’s only here to serve as a straw man for testing the whole bot mechanism; there’s not a lot of wisdom in this heuristic. It can also serve as a benchmark for testing other strategies.

The implementation of the nextMove method – the only method in the bot interface – is pretty straightforward: based on the current player playing (the side parameter), simply search for the cell with the most stones on that side of the board (lines 21-26 in SimpleAIPlayer.js). Note that this strategy is deterministic – given a board state, it will always choose the same cell². This is important when testing this, and also for testing this against other bot strategies.

Mancala Bot Wars

The next commit adds another simple AI bot player – Random AI Player, which simply picks a cell to play at random. This in itself isn’t very interesting. What is interesting³ is that now we have two types of bots, and we can run experiments on what strategy is better – we just pit the two bots against each other.

In order to do that, we’ll write some code that enables us to run the game with two bots and record the result. The next commit takes care of that:

	…

	program
	.version('0.0.1')
	.usage("Mancala Bot War: Run Mancala AI Experiment")
	.option('-p1, –player1 <AI 1 type>', "The bot to use for player 1")
	.option('-p2, –player2 <AI 2 type>', "The bot to use for player 2")
	.option('-r, –rounds <rnds>', "Number of games to play")
	.option('-o, –out <dir>', "output file")
	.parse(process.argv)

	…

	range(1,program.rounds*1).forEach(round => {
	dbg(`Round ${round}`)
	let game = new MancalaGame(14,'',_ => {},gameMsg,{p1 : program.player1, p2:program.player2},results => {
	dbg (`Round ${round} Results: ${results}`)
	let line = []
	line.push(results.player1StoneCount)
	line.push(results.player2StoneCount)
	line.push(results.winner \|\| 0) //write the player who one or 0 for draw
	fs.appendFileSync(program.out,line.join(',') + "\n",{flag :'a'})
	})
	game.start();

	})

view raw bots.js hosted with ❤ by GitHub

	class MancalaGame
	{
	constructor(gameSize,cnvsELID,_updatePlayerCallback,_showMsgCallback,requestedAIPlayers,_gameOverCallback)
	{
	…
	this.gameOverCallback = _gameOverCallback
	…
	if (cnvsELID)
	{
	this.boardUI = maybe(new BoardUI(cnvsELID,this.cellCount,this))
	this.boardUI.ifPresent(bui => bui.initializeBoardDrawing());
	}
	else this.boardUI = None; //headless mode
	}

	_redraw()
	{
	this.boardUI.ifPresent(_ => _.drawBoardState(this.board,this));
	}

	_gameOver()
	{
	let player1StoneCount = this.board.player1StoneCount();
	let player2StoneCount = this.board.player2StoneCount();

	let results = { player1StoneCount : player1StoneCount, player2StoneCount : player2StoneCount}

	switch (true)
	{
	case player1StoneCount > player2StoneCount : results.winner = 1; break;
	case player2StoneCount > player1StoneCount : results.winner = 2; break;
	default : results.isDraw = true; break;
	}

	this.gameOverCallback(results);
	}

	togglePlayer()
	{
	this.player = this.player.theOtherOne();
	this.boardUI.ifPresent(_ => _.toggleHighlights(this.player.number));
	return this.player;
	}
	}

view raw game.js hosted with ❤ by GitHub

	<script>
	function setup()
	{
	game = new main.MancalaGame(resolveGameSize(),'cnvsMain',updateCurrentPlayer,showMsg, resolveRequestedAI(),gameOver);
	game.start();
	}

	function gameOver(results)
	{
	let a = ["Game Over","# Stones P1:" + results.player1StoneCount,"# Stones P2: " + results.player2StoneCount];
	if (!results.isDraw)
	a.push(`Player ${results.winner} Wins!`)
	else
	a.push('Draw!')

	showMsg(a.join('<br/>'))

	}
	</script>

view raw index.html hosted with ❤ by GitHub

Mancala Bot Wars!

First, you’ll note the bots.js file, which is a simple script, invoked from the command line, that simply runs several rounds of the game and writes the results to a file. Every round creates a new game instance with the chosen player types, and calls game.start. It’s a script with some parameters, nothing fancy.

In order to support this, we need to refactor the MancalaGame class a bit. Specifically, we need it to be able to run w/o UI. This means two things: the game needs to run without a UI, and delivering the results has to be decoupled from the UI as well.

This is what happens in the game.js file. In lines 3,6 you can see we add a callback to announce that the game is over, and transmit the result. This callback is used in the _gameOver method, in line 35. Note that the code for showing the game over message moved out from this class (as it should); look for it in the index.html file.

In addition, we enable the client of the MancalaGame class to pass a null value for the cnvsELID constructor parameter, which signals to us that there’s no canvas UI to be used for this game instance. The boardUI member then becomes optional (lines 8-13) and whenever we access the boardUI, we need to make sure it’s present (lines 18,41).

We now have a game that can be run without human intervention, and play out solely with bots. We can now start experimenting with different game parameters, and see what strategy plays out better.

Prime geeky goodness.

Later commits clean up the bot experiment script, and add features. We also add other types of both player, with different heuristics (e.g. greedy capture, minimax player) so we can compare more strategies.

Building a Simple Game – Part 6

Leave a reply

Last time we implemented the ending of the game, and cleaned up the code a bit.

In this post we’ll look into an enhancement that allows us to change the size of the game, some more refactoring and bug fixes. At the end of this post we’ll be at the point where we have a playable game.

Altering the Game Size

One feature we’d like to add is the ability to play variable size of the Mancala game. We treat the total number of cells as the “size” of the game. Since each player has the same number of cells, this needs to be an even number, and cells are split evenly between players.

The next commit adds this feature:

	class MancalaGame
	{
	constructor(gameSize,cnvsELID,_updatePlayerCallback,_showMsgCallback)
	{
	…
	this.cellCount = gameSize;
	…
	this.board = new Board(this.cellCount);
	}

	_initializeBoardDrawing()
	{
	…
	drawBoard(cnvs,this.cellCount);
	…
	}
	}

view raw game.js hosted with ❤ by GitHub

	<script>

	const SIZE_PARAM_NAME = 'size';
	const DEFAULT_GAME_SIZE = 14;
	const GAME_SIZE_UPPER_BOUND = 28;
	const GAME_SIZE_LOWER_BOUND = 6;

	…

	function setup()
	{
	game = new main.MancalaGame(resolveGameSize(),'cnvsMain',updateCurrentPlayer,showMsg);
	}

	function resolveGameSize()
	{
	let params = new URLSearchParams(window.location.search);
	let size = (params.has(SIZE_PARAM_NAME) && !isNaN(params.get(SIZE_PARAM_NAME))) ?
	params.get(SIZE_PARAM_NAME)*1 : DEFAULT_GAME_SIZE;
	let ret = Math.max( //we bound the game size between the minimum and the upper bound
	Math.min(size
	,GAME_SIZE_UPPER_BOUND \|\| DEFAULT_GAME_SIZE)
	,GAME_SIZE_LOWER_BOUND);
	if (ret % 2 != 0) ret -= 1; //we have to make sure it's a divisble by 2.
	console.log("Game size: " + ret);
	return ret;
	}

	</script>

view raw index.html hosted with ❤ by GitHub

Adding option for variable game size

The implementation is pretty straightforward. Instead of having a constant (CELL_COUNT) in the controller module (game.js), we pass a parameter in the constructor (game.js, line 3), that is then fed to the Board data structure. The Board class already had this parameter, so it was already ready to work with any size, and did not assume a constant size.

What remains is simply having a way for the user to specify this. I decided to go with a simple URL parameter. This is simple enough to pass. So resolveGameSize in index.html (lines 15-27) takes care of reading the parameter from the URL query string and validating it. We then initialize the MancalaGame instance with this number (index.html line 12).

Again, Some Cleanup

The next two commits are really about a small but important refactoring. We’re encapsulating the board drawing in a class that takes care of all the drawing business, essentially encapsulating how the board is drawn and the user interaction with the board. The changes in drawing.js is mostly re-organization of different functions into class method (the BoardUI class). The more interesting part is how it’s actually used:

	…
	const {BoardUI} = require("./drawing.js")
	…

	class MancalaGame
	{
	constructor (…)
	{
	…
	this.boardUI = new BoardUI(cnvsELID,this.cellCount,this)
	this.boardUI.initializeBoardDrawing();
	}

	_redraw()
	{
	this.boardUI.drawBoardState(this.board,this);
	}

	togglePlayer()
	{
	this.player = this.player.theOtherOne();
	this.boardUI.toggleHighlights(this.player.number);
	return this.player;
	}

	}

view raw game.js hosted with ❤ by GitHub

Encapsulating the drawing code

The controller now doesn’t maintain a pointer to the canvas instance. Instead, it works through API provided by the BoardUI class, which is at a higher level of abstraction – initializeBoardDrawing, drawBoardState, toggleHighlights. The motivation here is really better encapsulation of the UI implementation.

The last commit for today takes care of one bug fix – making sure we skip the opponent’s mancala when making a move:

	class Board
	{
	…
	/**
	* Retrieve the cell number for the home (Mancala) of the given player.
	* @param {numer} player The number of the player whose Mancala we're seeking (1 or 2)
	* @returns The cell number for the given player's Mancala ( either 0 or totalCellCount/2)
	*/
	homeOf(player)
	{
	requires(player == 1 \|\| player == 2,"Player number can be either 1 or 2");
	return player == 1 ? this.player1Home() : this.player2Home();
	}
	}

view raw board.js hosted with ❤ by GitHub

	class MancalaGame
	{
	…

	playCell(boardCell)
	{
	…
	let targetCells = this._calculateTargetCellsForMove(boardCell);
	…
	}

	_calculateTargetCellsForMove(fromCell)
	{
	let _ = this.board;
	let stepCount = _.stonesIn(fromCell);
	dbg("Playing " + stepCount + " stones from cell " + fromCell)
	let targetCells = range(1,stepCount)
	.map(steps => _.cellFrom(fromCell,steps,this.player.number))
	.filter(c => c != _.homeOf(this.player.theOtherOne().number)) //remove, if applicable, the cell of the other player's mancala
	while (targetCells.length < stepCount) //add any cells, until we reach a situation where we have enough holes to fill (per the stone count in the played cell)
	{
	let addedCell = _.cellFrom(targetCells[targetCells.length-1],1)
	if (addedCell == _.homeOf(this.player.theOtherOne().number))
	targetCells.push(_.cellFrom(addedCell,1))
	else
	targetCells.push(addedCell)
	}
	return targetCells;
	}
	}

view raw game.js hosted with ❤ by GitHub

Fixing a bug – skipping the opponents Mancala (home)

There’s nothing too fancy here. The gist of the fix is in lines 17-19 in the MancalaGame class⁴.

Incorporating this fix, however, prompted me to extract the calculation of the target cells to a different function (_calculateTargetCellsForMove), so the playCell function remains at the same level of abstraction, and is still readable⁵.

And We’re Done …

At this point, one should be able to build the code (npm run build) and point his browser to the resulting index.html. Look for it in the dist directory.

A working version of the game is available here, embedded here for your convenience:

Admittedly, it’s not much to look in terms of UI design. But it’s a simple game we did in a few hours time, and it works. If you followed along so far, give yourself a pat on the shoulder.

… But Wait, There’s More

The story of how to create a simple game is pretty much done. But there’s more that can be said and done here, more features to build, tweaks to do.

Concrete examples for more directions include better UI design, more features (undo/redo, saving game states, showing a log, etc.). I welcome any more suggestions, and of course pull requests.

If you look at the repo, you’ll see that I went in another direction for enhancement. I was more interested in incorporating bots (“AI”) into the game as a feature; so you could play against a bot, or even have two bots play against each other. Stay tuned for more on that front.

Building a Simple Game – Part 5

Leave a reply

Last time we started really adding meat – the logic of the game rules. Today we’re going to look into some more logic, and how we wrap it up.

Ending a Game

It’s a game, but it does have to end at some point. This commit take care of exactly that – identifying the condition that ends the game and stops processing new moves:

	class MancalaGame
	{
	constructor(cnvsELID,_updatePlayerCallback,_showMsgCallback)
	{
	…
	this.gameDone = false;
	…
	}

	handleCellClick(boardCell)
	{ //todo: clean this up
	if (this.gameDone)
	{
	dbg("Game over, get outta here");
	return;
	}
	…
	let currentPlayerHasNoMoreMoves = this.player1Playing(this.board.allPlayer1Cells(c => this.board.stonesIn(c) <= 0)) \|\|
	this.player2Playing(this.board.allPlayer2Cells(c => this.board.stonesIn(c) <= 0))
	if (currentPlayerHasNoMoreMoves)
	this.gameOver();

	this.canvas.ifPresent(cnvs => {
	drawBoardState(cnvs,this.board,this)
	})

	}
	}

	gameOver()
	{
	let player1StoneCount = this.board.player1StoneCount();
	let player2StoneCount = this.board.player2StoneCount();

	let a = ["Game Over","# Stones P1:" + player1StoneCount,"# Stones P2: " + player2StoneCount];
	switch (true)
	{
	case player1StoneCount > player2StoneCount : a.push("Player 1 Wins!"); break;
	case player2StoneCount > player1StoneCount : a.push("Player 2 Wins!"); break;
	default : a.push("Draw!"); break;
	}

	this.showMsg(a.join("<br/>"));
	this.setGameOver();
	}

	setGameOver() { this.gameDone = true; }

	}

view raw game.js hosted with ❤ by GitHub

Game over functionality

The implementation is pretty straightforward: we add a simple flag (gameOver) to the MancalaGame class (line 6) and consult it before processing any move (line 12). Of course, we have to take care of setting the flag properly, which happens at lines 18-21.

The gameOver function (lines 30-45) takes care of 3 main things⁶:

Determining the winner (lines 36-41)
Notifying the UI (lines 35,43)
Setting the gameOver flag (line 44).

The implementation is pretty simple and straightforward, but admittedly, this function does a bit too much. We’ll take care of that right away.

Also, taking care of the message displayed to the user is not ideal thing to do here, but it’s not terrible, in my opinion, in this case.

Some Cleanup Is In Order

At this point, it has become quite clear that the handleCellClick function was becoming convoluted. It was quickly approaching the point of being unmanageable, doing too many things and operating at different levels of abstraction; e.g. encoding game rules while also taking care of UI messages. It was time for some cleaning.

The next commit ⁷ did exactly that:

	class MancalaGame
	{
	constructor(cnvsELID,_updatePlayerCallback,_showMsgCallback)
	{
	…
	this._initializeBoardDrawing();
	}

	_initializeBoardDrawing()
	{
	this.canvas.ifPresent(cnvs => {
	…
	})
	}

	handleCellClick(boardCell)
	{
	if (!this.gameDone)
	{
	this._resetGameMessagePanel();
	if (this.isValidMove(boardCell))
	this._makeMove(boardCell)
	else
	this.showMsg("Invalid Move")
	}
	else dbg("Game over, stop procrastinating")
	}

	_makeMove(boardCell)
	{
	let lastCell = this.playCell(boardCell);
	this._togglePlayerOrExtraTurn(lastCell)
	this._checkAndDeclareGameOverIfNecessary()
	this._redraw();
	}

	_resetGameMessagePanel()
	{
	this.showMsg(" ")
	}

	_togglePlayerOrExtraTurn(lastCell)
	{
	let lastCellIsHomeOfCurrentPlayer = this.player1Playing(this.board.isPlayer1Home(lastCell)) \|\|
	this.player2Playing(this.board.isPlayer2Home(lastCell))
	if (!lastCellIsHomeOfCurrentPlayer)
	this.updatePlayerCallback(this.togglePlayer());
	else
	this.showMsg("Extra Turn")
	}

	_checkAndDeclareGameOverIfNecessary()
	{
	let currentPlayerHasNoMoreMoves = this.player1Playing(this.board.allPlayer1Cells(c => this.board.stonesIn(c) <= 0)) \|\|
	this.player2Playing(this.board.allPlayer2Cells(c => this.board.stonesIn(c) <= 0))
	if (currentPlayerHasNoMoreMoves)
	this._gameOver();
	}

	_redraw()
	{
	this.canvas.ifPresent(cnvs => {
	drawBoardState(cnvs,this.board,this)
	})
	}

	playCell(boardCell)
	{
	let _ = this.board;
	let targetCells = range(1,_.stonesIn(boardCell)).map(steps => _.cellFrom(boardCell,steps))
	let lastCell = targetCells[targetCells.length-1];
	let lastCellWasEmpty = _.stonesIn(lastCell) == 0;
	targetCells.forEach(c => _.addStoneTo(c));
	this._checkAndCaptureIfNecessary(lastCell,lastCellWasEmpty);

	_.setCellStoneCount(boardCell,0);

	return lastCell;
	}

	_checkAndCaptureIfNecessary(lastCell,lastCellWasEmpty)
	{
	let _ = this.board;
	let isLastCellAHomeCell = _.isPlayer1Home(lastCell) \|\| _.isPlayer2Home(lastCell);
	let lastCellBelongsToCurrentPlayer = this.player1Playing(_.isPlayer1Cell(lastCell)) \|\|
	this.player2Playing(_.isPlayer2Cell(lastCell))
	if (lastCellWasEmpty && !isLastCellAHomeCell && lastCellBelongsToCurrentPlayer)
	{ //capture the stones from the other player
	let acrossCell = _.totalCellCount() – lastCell;
	dbg("Capturing stones from " + acrossCell + " to " + lastCell)
	_.setCellStoneCount(lastCell,_.stonesIn(lastCell) + _.stonesIn(acrossCell));
	_.setCellStoneCount(acrossCell,0);
	}
	}
	}

view raw game.js hosted with ❤ by GitHub

Cleaning up

The gist of what we’re doing here is a simple refactoring of “extract method”: taking a few lines of code, extracting them into a separate function/method and invoking that function in the right location. The main motivation is breaking down a long function into more digestible pieces, making the code more readable. There’s not even a lot of code reuse going on around here, which might be another motivation for extracting a piece of code into another function. The resulting code is, in my opinion, easier to follow, and troubleshoot in the future. Function logic is expressed more succinctly and in a more consistent level of abstraction.

Take for example the new handleCellClick function (lines 16-27 above). If you read it, its functionality can be summarized in one sentence: “reset the message panel, then assuming the game isn’t over and the move is valid, make the move”.

Similarly, the _makeMove function (lines 29-35 above), that is being called from the handleCellClick function, can be summarized in one sentence: “play the cell passed, then considering the last cell reached, decide if an extra turn is in place; check if we reached the end of the game and redraw the board.”⁸

This mental exercise of trying to describe a function’s implementation in a sentence or two⁹ is an important one when trying to assess the readability of the code, which from my experience is a crucial quality factor. I believe it’s hard to assess readability with an objective criteria, but when writing and reading my code, this is how I try to assess it.

Bug Fixing and a UI Improvement

The next two commits, affectionately known as 38feec5 and 8879f31¹⁰, take care of fixing a bug, and making a small (but significant) addition to the user interface:

	_checkAndCaptureIfNecessary(lastCell,lastCellWasEmpty)
	{
	let _ = this.board;
	let isLastCellAHomeCell = _.isPlayer1Home(lastCell) \|\| _.isPlayer2Home(lastCell);
	let lastCellBelongsToCurrentPlayer = this.player1Playing(_.isPlayer1Cell(lastCell)) \|\|
	this.player2Playing(_.isPlayer2Cell(lastCell))
	if (lastCellWasEmpty && !isLastCellAHomeCell && lastCellBelongsToCurrentPlayer)
	{ //capture the stones from the other player
	let acrossCell = _.totalCellCount() – lastCell;
	let targetHome = this.player == PLAYER.one ? _.player1Home() : _.player2Home();
	let totalCapturedStones = _.stonesIn(lastCell) + _.stonesIn(acrossCell);
	dbg("Capturing stones from " + acrossCell + " and " + lastCell + " to " + targetHome + ". Total: " + totalCapturedStones )
	_.setCellStoneCount(targetHome,_.stonesIn(targetHome) + totalCapturedStones);
	_.setCellStoneCount(acrossCell,0);
	_.setCellStoneCount(lastCell,0);
	}
	}

view raw game.js hosted with ❤ by GitHub

Properly Capturing Stones

The logic for capturing the stones is pretty straightforward. One thing to note is that the bug fix is localized in one place¹¹ – a testament to good code structure; though, to be fair, this isn’t really a cross-cutting concern. Another thing to note is the calculation of the cell across from the last cell – acrossCell (line 9) – the simple calculation can be done because we rely on array indices. A better implementation would have deferred this to the Board class, and exposed a method named something like getAcrossCell(fromCell), so we can let this implementation detail remain in the Board class; this is an example of an abstraction leak (anyone up for a pull request to fix this?).

The second commit takes care of creating and toggling the highlighting of the current player:

	function createHighlights(cellCount)
	{
	…
	let w = (_boardWidthInCells -2)* CELL_SIZE;
	let t = TOP_LEFT.y;
	let l = TOP_LEFT.x + CELL_SIZE;
	let boardHeightInCells = 3;
	p1Highlight = new fabric.Line([l,t,l+w,t],{selectable:false,stroke:'red',strokeWidth:3})
	p2Highlight = new fabric.Line([l,t+(boardHeightInCellsCELL_SIZE),l+w,t+(boardHeightInCellsCELL_SIZE)],{selectable:false,stroke:'red',strokeWidth:3})
	…
	}

	function toggleHighlights(canvas,player)
	{
	requires(player == 1 \|\| player == 2,"Invalid player when switching highlights")
	switch (player)
	{
	case 1 :
	canvas.add(p1Highlight);
	canvas.remove(p2Highlight);
	break;
	case 2 :
	canvas.add(p2Highlight);
	canvas.remove(p1Highlight);
	break;
	}
	}

view raw drawing.js hosted with ❤ by GitHub

	_initializeBoardDrawing()
	{
	…
	toggleHighlights(cnvs,this.player.number)
	}

	togglePlayer()
	{
	…
	this.canvas.ifPresent( cnvs => {
	toggleHighlights(cnvs,this.player.number);
	})
	…
	}

view raw game.js hosted with ❤ by GitHub

Highlighting the Current Player

Technically, the highlight itself is simply drawing a red line on the border of the current player’s side of the board. We create 2 instances of fabric.Line in the drawing module, and then simply add and remove them to the canvas when necessary. Note that the toggleHighlights function in the drawing module (line 13) receives the player’s number and queries it directly. I don’t see this as a case of using magic numbers since the numbers themselves are clearly representative of the player object they’re representing, 1 for player 1, and 2 for player 2. I preferred avoiding exposing directly the the PLAYER objects in the game module (game.js).

We’re almost done. Next time we’re going to add a feature, cleanup a bit, and fix a bug; at which point we should have a working version of the game.

Building a Simple Game – Part 4

Leave a reply

So after we hooked up and setup the skeleton of the game, it’s time to add some more meat – actually implementing the rules of the game.

Validating a Move

In our next commit¹², we introduce the notion of validating a move:

	handleCellClick(boardCell)
	{
	if (!this.isValidMove(boardCell))
	this.showMsg("Invalid Move")
	else
	{
	this.showMsg(" ")
	this.board.playCell(boardCell);
	this.updatePlayerCallback(this.togglePlayer());

	this.canvas.ifPresent(cnvs => {
	drawBoardState(cnvs,this.board,this)
	})

	}
	}

	isValidMove(boardCell)
	{
	let isValidPlayer1Move = this.player == PLAYER.one && this.board.isPlayer1Cell(boardCell);
	let isValidPlayer2Move = this.player == PLAYER.two && this.board.isPlayer2Cell(boardCell);
	return isValidPlayer1Move \|\| isValidPlayer2Move;
	}

view raw game.js hosted with ❤ by GitHub

Validating a move

The logic is simple: when we’re handling a cell click, i.e. a request to make a move, we first make sure the move is legal/valid. If it is, we make the move (line 8), and update the UI as before. If it’s not valid, we ask the UI to show some error message¹³. Note that some UI work – showing a message, displaying who is the current player – happen regardless of the canvas being there or not.

The validation function itself – isValidMove – is fairly straightforward at this point. It merely checks that the move is of a cell that belongs to the current player. What’s more important is that we have a specific place to validate a move. We can augment it with further rules later. Another design choice made here is that the isValidMove function returns a boolean result – a move is either valid or not, without any specification of the nature of the problem. A more robust mechanism would’ve returned some indication of the actual problem with the move; mostly for the purpose of showing the player a reason for rejecting the move.

Capturing Stones

Our next commit does two important things:

	handleCellClick(boardCell)
	{
	if (!this.isValidMove(boardCell))
	…
	else
	{
	…
	this.playCell(boardCell); //was: this.board.playCell(boardCell);
	…
	}
	}

	playCell(boardCell)
	{
	let _ = this.board;
	let targetCells = range(1,_.stonesIn(boardCell)).map(steps => _.cellFrom(boardCell,steps))
	let lastCell = targetCells[targetCells.length-1];
	let isLastCellEmpty = _.stonesIn(lastCell) == 0;
	let isLastCellAHomeCell = _.isPlayer1Home(lastCell) \|\| _.isPlayer2Home(lastCell);
	let lastCellBelongsToCurrentPlayer = (_.isPlayer1Cell(lastCell) && this.player == PLAYER.one) \|\|
	(_.isPlayer2Cell(lastCell) && this.player == PLAYER.two)

	targetCells.forEach(c => _.addStoneTo(c));

	if (isLastCellEmpty && !isLastCellAHomeCell && lastCellBelongsToCurrentPlayer)
	{ //get the stones from the other player
	let acrossCell = _.totalCellCount() – lastCell;
	_.setCellStoneCount(lastCell,_.stonesIn(lastCell) + _.stonesIn(acrossCell));
	_.setCellStoneCount(acrossCell,0);
	}

	_.setCellStoneCount(boardCell,0);

	}

view raw game.js hosted with ❤ by GitHub

Capturing stones + important refactoring

First, we fix an old “wrong”. We move the function the implements the game rule into the MancalaGame class. Remember that when we reviewed the code in the past we took note of this issue; we’re now fixing it.

Next, we’re implementing another game rule – capturing stones. The logic isn’t very complicated, it’s basically encoding the game rule directly – see if we finished in an empty cell, and assuming it’s in the current player’s side, capture the stones from the opponent’s cell right across the board.

From a design point of view, we’re only doing here a change in the board’s state – mutating the local Board instance using its mutating methods (addStoneTo, setCellStoneCount). So we maintain the separation of concerns as we intended: isValidMove validates the move, playCell changes the board as necessary and drawBoardState updates the UI with the new state.

Extra Turn

Our next commit takes care of another rule – a player gets an extra turn if his move ended in his home (his Mancala):

	handleCellClick(boardCell)
	{
	this.showMsg(" ")
	if (!this.isValidMove(boardCell))
	this.showMsg("Invalid Move")
	else
	{
	let lastCell = this.playCell(boardCell);
	let lastCellIsHomeOfCurrentPlayer = this.player1Playing(this.board.isPlayer1Home(lastCell)) \|\|
	this.player2Playing(this.board.isPlayer2Home(lastCell))
	if (!lastCellIsHomeOfCurrentPlayer)
	this.updatePlayerCallback(this.togglePlayer());
	else
	this.showMsg("Extra Turn")

	…
	}
	}

	player1Playing(andAlso)
	{
	return this.player == PLAYER.one && (typeof(andAlso) == undefined ? true : andAlso);
	}

	player2Playing(andAlso)
	{
	return this.player == PLAYER.two && (typeof(andAlso) == undefined ? true : andAlso);
	}

	playCell(boardCell)
	{
	…
	let lastCellBelongsToCurrentPlayer = this.player1Playing(_.isPlayer1Cell(lastCell)) \|\|
	this.player2Playing(_.isPlayer2Cell(lastCell))

	…
	return lastCell;
	}

view raw game.js hosted with ❤ by GitHub

Adding the rule for extra turn

The logic of the rule itself is in lines 9-14 above, and pretty straightforward to follow. Note how we create here an interaction with the playCell function. The playCell is primarily concerned with updating the board data structure (this.board). And returns an indication of the last cell played. The rest of the logic is in its calling function (handleCellClick), which checks for validity and tests for the extra turn. The game logic is still centralized in the same class, MancalaGame, but we’re also keeping a separation between the different functions, trying to maintain the cohesion of each function on its own.

Another small point to take note of here is a small refactoring, mainly for code readability. There are now at least 2 places checking for a specific condition only if a specific player is currently playing (lines 9,10 and 33,34 in the snippet above). My “DRY itch”¹⁴ came alive when seeing this, so the pattern is extracted into separate functions – player1Playing, player2Playing. We’ll see later how this pattern of identifying a condition based on the current player that’s playing repeats itself so this will come in handy down the road as well.

Next we’re going to look into how we identify when the game is over, and implement it. We’ll also wrap up this basic version of the game, and look into what else can be done.

Building a Simple Game – Part 3

Leave a reply

Continuing our journey to creating a game, after drawing the board, we should make sure the UI is actually responsive and a user can actually play the game.

The first interesting bit here is translating a UI click (mousedown event) to a change in the game state, and drive a redrawing of the new state.

	class Board
	{
	…

	playCell(cell)
	{
	range(1,this.stonesIn(cell))
	.map(steps => this.cellFrom(cell,steps))
	.forEach(c => this.addStoneTo(c))

	this.setCellStoneCount(cell,0);
	}

	/**
	* Calculate a target cell, given a new cell, walking counter-clockwise a number of steps as given
	* @param {number} cell The cell we're starting from
	* @param {number} steps The number of steps to take from this cell, counter-clockwise, to reach the new cell
	*/
	cellFrom(cell,steps)
	{
	//walk backwards, and if we pass cell 0, add the number of cells again.
	return cell – steps + (cell < steps ? this.totalCellCount() : 0);
	}

	addStoneTo(cell)
	{
	this.setCellStoneCount(cell,this.stonesIn(cell)+1)
	}
	}

view raw board.js hosted with ❤ by GitHub

	function drawBoardState(cnvs,board,boardClickHandler)
	{
	…

	function drawOrRemove(boardCell,stoneCount,drawFunc)
	{
	if (stoneCount > 0)
	{
	removeDrawingAt(boardCell);
	drawFunc(boardCell,stoneCount);
	uiObjAt(boardCell).ifPresent(uiObj => {uiObj.on('mousedown', _ => { boardClickHandler(boardCell); })})
	}
	else removeDrawingAt(boardCell);
	}

	}

view raw drawing.js hosted with ❤ by GitHub

	var canvas = None;

	function initGame(cnvsELID)
	{
	canvas = maybe(initCanvas(cnvsELID));
	canvas.ifPresent(cnvs => {
	initDrawingElements(board.totalCellCount());
	drawBoard(cnvs,CELL_COUNT);
	drawBoardState(cnvs,board,boardClickHandler);
	})
	}

	function boardClickHandler(boardCell)
	{
	board.playCell(boardCell);
	canvas.ifPresent(cnvs => {
	drawBoardState(cnvs,board,boardClickHandler)
	})
	}

view raw game.js hosted with ❤ by GitHub

Connecting a UI event to actual state change

So what’s going on here¹⁵?

If you remember, we already added an event listener to the mousedown event, when creating the necessary UI objects. At this point, we’re making sure it’s actually responding. Since we want the concern of responding to events to be contained in the controller (the game.js module), we add a callback function to the drawBoardState function and make sure it’s invoked at the correct time – when the mousedown event is fired. Note that at the point we attach the event, we’re already aware of the cell we’re attaching it to (the boardCell parameter is part of the closure), so this saves us the need to translate a UI object (or coordinates) to a game object/concept – the cell.

Looking at the callback function implementation – boardClickHandler in game.js – we see a rather simple implementation. We ask the board module to “play” the cell, i.e. play the stones in that cell – make a move. This is a new mutating method in the Board class. Then, assuming the canvas is available, the handler asks the drawing module to draw the new state again.

Finally, looking at the addition to the Board class, we can see how it’s “taking” all stones in the cell and adding one stone to each of the next cells counter clockwise, as per the Mancala rules + empties the played cell (line 11 in board.js above). The result of this method execution is a new state of the cells in the board data structures – a new count for some of the cells.

Note that all state changes in the board are expressed through one method – setStoneCellCount, this is intentional and will prove useful later. When coding, you don’t always foresee the future and where some choices might be useful. In this case, the benefit wasn’t immediately apparent. Still, I stuck to a simple principle of trying to express higher level functionality (playing a cell) using lower level functionality that’s already defined. This is basic structuring of the code, in this case following the DRY principle. At the very least it helps with readability, which is important by itself. In this case it also helps with encapsulation.

A Short Code Review

It’s important to acknowledge the fact that design choices are made as we write the code, not only upfront. It’s therefore worth stopping and reviewing what choices were made here.

First, if you look at the code, you can see that the Board module exposes the playCell method. This is in fact encoding a game rule – how a certain move is made in the game. We should be asking ourselves whether this is the right place for this kind of concern to be implemented. Admittedly, when writing the code I simply wrote it this way w/o giving it a second thought. This goes to show how sometimes such choices are made when we’re not paying attention. We’ll get back to this point later, when it’s actually fixed.

Second thing to note is that the canvas variable is in fact an Option type. Meaning, we could be running the game without a canvas to paint on. The code in the game module (the controller) is of course aware of this and explicitly asks whether the canvas is there, e.g. lines 6,16 in game.js. This is intentional – we would like to be able to run the game even when technically there’s no way to draw it (can you think why?). Of course, one has to ask whether the way to represent the fact that we’re running w/o a GUI is by managing the underlying drawing object (the canvas) in the controller…

Third thing to note is that throughout the code, we’re referring to the notion of the board cell by implementing it as a simple integer. In most cases this is not evident, we’re just passing a “board cell”, without specifying the type. It’s mostly evident in the board data structure itself (board.js), where we answer some queries by simply comparing numbers to the given cell. This is an intentional design choice made for simplification. I do not see a lot of benefit in defining a separate class representing a board cell. If I was using a more explicitly typed language, I would probably be aliasing the integer to a more readable type, e.g. in Scala: type BoardCell = Int. But this is not available nor needed in JS. As long as we keep that piece of knowledge (“board cell is in fact a simple integer”) confined to one module – the board data structure – we should be fine with this choice.

A Bit of Refactoring and Introducing Players

Our journey continues with a commit that is mostly about refactoring the controller. This is where the controller module (game.js) is rewritten to expose a class – MancalaGame, with an explicit interface:

	…
	class MancalaGame
	{
	constructor(cnvsELID,_updatePlayerCallback)
	{
	requires(_updatePlayerCallback != null,"Must have a player update callback")

	this.board = new Board(CELL_COUNT);
	this.player = PLAYER.one;
	this.updatePlayerCallback = _updatePlayerCallback;
	this.updatePlayerCallback(this.player);

	this.canvas = maybe(initCanvas(cnvsELID));
	this.canvas.ifPresent(cnvs => {
	…
	})
	}

	handleCellClick(boardCell)
	{
	this.board.playCell(boardCell);
	this.updatePlayerCallback(this.togglePlayer());

	this.canvas.ifPresent(cnvs => {
	drawBoardState(cnvs,this.board,this)
	})
	}

	togglePlayer()
	{
	this.player = this.player.theOtherOne();
	return this.player;
	}
	}

view raw game.js hosted with ❤ by GitHub

The new MancalaGame class

This is done mostly for readability and for encapsulating whatever is necessary to run the game, as more and more pieces of logic and data come up. Note specifically that the board data structure, the canvas and associated callbacks are members of this class.

Another notion we’re introducing is that of the current player. The game has a current player in place, and the controller (MancalaGame) keeps track of it. Since we’re working under the assumption that there’re always exactly 2 players in this game, we can simply code them as constant objects:

	const PLAYER = {
	one : {
	toString : () => "ONE"
	, theOtherOne : () => PLAYER.two
	}
	, two : {
	toString : () => "TWO"
	, theOtherOne : () => PLAYER.one
	}
	}

view raw game.js hosted with ❤ by GitHub

Defining players

Note that while not explicitly exposed (from module.exports) these objects are in fact an API for this module, since they will be used by other modules. The togglePlayer method in MancalaGame actually exposes these objects. Also note that players are not represented by mere numbers (1,2), but as actual objects¹⁶. This is mainly because I want to have an explicit interface that encapsulate the current player, and being able to send messages to that object in different scenarios. For example, I’d like to display the player name (“ONE”, “TWO”) in the UI, and also toggle the players easily. Encapsulating the player behavior in an object (vs. representing as a simple number) is therefore more useful. We’ll see later where this comes in handy in more places.

So far, we’ve setup how the game is displayed, and the main mechanics of interaction. We have a skeleton of the game and the needed data structures to support implementing the logic. Next, we’ll start implementing more and more logic of the game, and see how this affects the code design.

Building a Simple Game – Part 2

Leave a reply

So after a short introduction to the project, let’s dive into some commits.

Our story starts with this commit, where we set the basis for drawing the board.

A lot of the files there are boiler plate (webpack config, package.json). The interesting parts are the index.js and drawing.js files:

	function initCanvas(canvasEl)
	{
	let ret = canvasEl && (new fabric.Canvas(canvasEl));
	if (ret)
	{
	ret.line = (x1,y1,x2,y2,c) => drawLineOn(ret,x1,y1,x2,y2,c);
	}
	return ret;
	}

	function drawBoard(cnvs)
	{
	let CELL_SIZE = 50;
	let CELL_COUNT = 14;

	let TOP_LEFT = { x : 50, y : 50};

	let playerCellCount = CELL_COUNT/2-1;
	let boardWidthInCells = playerCellCount+2 //for the side cells (player homes)
	let boardHeightInCells = 3;

	//frame
	horizLine(TOP_LEFT.x,TOP_LEFT.y,boardWidthInCells * CELL_SIZE); //top left to top right
	verticalLine(TOP_LEFT.x,TOP_LEFT.y,CELL_SIZE*boardHeightInCells); //top left to bottom left
	horizLine(TOP_LEFT.x,TOP_LEFT.y + CELL_SIZEboardHeightInCells,boardWidthInCells CELL_SIZE); // bottom left to bottom right
	verticalLine(TOP_LEFT.x + boardWidthInCells * CELL_SIZE,TOP_LEFT.y,CELL_SIZE * boardHeightInCells); //top right to bottom right

	//home cells
	verticalLine(TOP_LEFT.x + CELL_SIZE,TOP_LEFT.y,CELL_SIZE*boardHeightInCells)
	verticalLine(TOP_LEFT.x + CELL_SIZE(boardWidthInCells-1),TOP_LEFT.y,CELL_SIZEboardHeightInCells)

	//cell horizontal lines
	let upperCellY = TOP_LEFT.y + CELL_SIZE;
	let lowerCellY = TOP_LEFT.y + CELL_SIZE*2;
	let lineLen = (boardWidthInCells-2)*CELL_SIZE;

	horizLine(TOP_LEFT.x + CELL_SIZE,upperCellY,lineLen)
	horizLine(TOP_LEFT.x + CELL_SIZE,lowerCellY,lineLen)

	//cell borders
	range(2,CELL_COUNT/2).map(cellNum => {
	verticalLine(TOP_LEFT.x + cellNum*CELL_SIZE,TOP_LEFT.y,CELL_SIZE)
	verticalLine(TOP_LEFT.x + cellNumCELL_SIZE,TOP_LEFT.y+CELL_SIZE(boardHeightInCells-1),CELL_SIZE)
	} )

	function verticalLine(x,y,len) { cnvs.line(x,y,x,y+len); }

	function horizLine(x,y,len) { cnvs.line(x,y,x+len,y); }

view raw drawing.js hosted with ❤ by GitHub

	function initGame(cnvsELID)
	{

	drawBoard(initCanvas(cnvsELID));
	}

view raw index.js hosted with ❤ by GitHub

index.js and drawing.js – the interesting parts.

The index.js is the start of the MancalaGame I mentioned previously. Similarly, the drawing.js is the start of the BoardUI module mentioned as well. Both are written as node modules that export the necessary API as functions to be used by other modules.

At this point, not a lot is going on. We expose a single function from index.js which basically only asks the drawing module to initialize the canvas and draw the board.

Initializing the canvas is simply initializing a fabric.js object with our given HTML canvas element. We’re adding there another function for easier writing (and reading) later, but not much more. We’re doing this so we can leverage the fabric.js API for drawing on the canvas. We’ll be using this object from now on to manipulate the canvas.

Drawing the board itself is simply a matter of calculating line lengths and locations, nothing more. Note how the cell size, number and location of the board are all hard-coded into the function. We’re avoiding magic numbers, which is good. But this is clearly not very extendible or configurable code.

At the end of this step we can launch the index.html file which simply calls the game initGame function we mentioned above when the page loads.

Our next commit is a simple refactoring – renaming the index.js file to game.js. This is a simple enough refactoring, but I wouldn’t dismiss it so easily. It’s important to maintain a mental model of what each module does and how it’s connected to other modules in the code. I described that model in the previous post, and this is where it is manifested. It starts with the file names; designing the API and how it’s used is easier when we have some idea of where different responsibilities lie. It’s easier to track this when we know what module we’re working on by simply looking at the file name¹⁷.

Drawing Board State

So far, we only drew the board itself, but no stones in it. If we only do minimal changes, we’d probably only be drawing circles and numbers at this point (to represent how much stones are in each cell). But there’s a more fundamental idea here. We’re in fact drawing the state of the game onto the board. At the start of the game there’s obviously an initial state of the board setup. But the more prominent idea here is that of drawing the state of the board onto the canvas, in correct places. In other words, we need some representation of the board state.

Enter board.js:

	class Board
	{
	constructor(_cellCount)
	{
	this.cellCount = _cellCount;
	this.board = [];
	range(1,this.cellCount).forEach(_ => this.board.push(0))
	this.forAllPlayer1Cells(cellInd => this.setCellStoneCount(cellInd,INITIAL_STONE_COUNT))
	this.forAllPlayer2Cells(cellInd => this.setCellStoneCount(cellInd,INITIAL_STONE_COUNT))
	dbg("Board initialized")
	}

	forAllPlayer2Cells(f) { … }

	forAllPlayer1Cells(f) { … }

	setCellStoneCount(boardCell,cnt) { this.board[boardCell] = cnt }
	stonesIn(boardCell) { return this.board[boardCell]}

	forAllCells(f) { … }

	isPlayer1Cell(boardCell) { return boardCell >= 1 && boardCell <= this.cellCount/2-1; }
	isPlayer2Cell(boardCell) { return boardCell >= this.cellCount/2+1 && boardCell <= this.cellCount-1; }

	isPlayer1Home(boardCell) { return boardCell == 0; }
	isPlayer2Home(boardCell) { return boardCell == this.cellCount/2; }

	totalCellCount() { return this.cellCount; }
	}

view raw board.js hosted with ❤ by GitHub

Board.js, initial version

This module exports a single class – Board, which maintains the data structure for maintaining the board state.

The state itself is maintained as a simple array of numbers – one number per board cell + the board’s cell count (the game’s “size”). But the array itself is not directly exposed. All API of the class does some query/manipulation over that array.

Note that there’s only one mutating method – setCellCount, which is the only method (for now) that changes the state. All other methods are simply querying the board’s state, or iterating over it.

One other noteworthy choice at this point: the API encodes the fact that there are only 2 possible players, e.g. by defining methods such as isPlayer1Cell, isPlayer2Cell. This is a deliberate choice, working under the assumption that the game, and its accompanying state, would only have 2 players playing. Accounting for a possibility of more players doesn’t seem useful, and more importantly worth the complication it could cause in the code. We’re “hard-coding” this choice (the number of players), but benefit by having a simpler and explicit API to the game’s state. This will also translate into easier expression of the game rules as we’ll see later.

Drawing the board state requires then a new function – drawBoardState in the drawing module:

	function drawBoardState(cnvs,board)
	{
	board.forAllCells(boardCell => {
	let stonesInCell = board.stonesIn(boardCell);
	switch (true)
	{
	case board.isPlayer1Home(boardCell) : drawPlayer1Home(stonesInCell); break;
	case board.isPlayer2Home(boardCell) : drawPlayer2Home(stonesInCell); break;
	case board.isPlayer1Cell(boardCell) \|\| board.isPlayer2Cell(boardCell): drawCell(boardCell,stonesInCell); break;
	default : ERR ("Invalid board cell when drawing state: " + boardCell); break;
	}
	})

	function drawPlayer1Home(stoneCount)
	{
	drawText(stoneCount,TOP_LEFT.x + CELL_SIZE / 2 – 10,TOP_LEFT.y + CELL_SIZE * 1.5 – 10)
	}

	function drawPlayer2Home(stoneCount)
	{
	drawText(stoneCount,TOP_LEFT.x + boardWidthInCells(board.totalCellCount()) * CELL_SIZE – CELL_SIZE/2 – 10,TOP_LEFT.y + CELL_SIZE*1.5-10)
	}

	function drawText(txt,left,top)
	{
	cnvs.add(new fabric.Text(txt+'',{fontSize : 20, left : left, top : top}))
	}
	}

view raw drawing.js hosted with ❤ by GitHub

Querying and drawing the board state

This function is now exposed outside, as another API function from drawing.js. There’s not a lot going on here except calculating positions and sizes for text elements. We can already see the meaning of choosing to be explicit in our API about player 1 and 2 – the function simply dispatches the correct calculation based on the characterization of the cell.

Tying It Together

To make sure all this drawing actually takes place, we make sure to tie it together. This happens by calling the new function from our controller module, `game.js`:

	const CELL_COUNT = 14;

	let board = new Board(CELL_COUNT)

	function initGame(cnvsELID)
	{

	drawBoard(initCanvas(cnvsELID));
	let cnvs = initCanvas(cnvsELID)
	drawBoard(cnvs,CELL_COUNT);
	drawBoardState(cnvs,board);
	}

view raw game.js hosted with ❤ by GitHub

Making sure we actually draw the state

At this point, we’re only adding the call to draw the state from the game initialization function. Note how at this point we already need to extract the CELL_COUNT constant. It was previously in the drawBoard state, in drawing.js; now it’s extracted to the game module, and used both to initialize the board data structure itself, as well as the drawing the board (lines 3,10 in the above snippet).

Drawing the Cell

Our next commit takes care of drawing the actual cell count in the cells:

	function drawCell(boardCell,stoneCount)
	{
	var left = 0;
	var top = 0;
	switch (true)
	{
	case board.isPlayer1Cell(boardCell) :
	top = CELL_SIZE /2 – FONT_SIZE/2;
	left = boardCell * CELL_SIZE + CELL_SIZE/2 – FONT_SIZE/2;
	break;
	case board.isPlayer2Cell(boardCell) :
	top = CELL_SIZE * 2.5 – FONT_SIZE/2;
	left = (board.totalCellCount() – boardCell) * CELL_SIZE + CELL_SIZE/2 – FONT_SIZE/2;
	break;
	default : ERR("Invalid board cell: must be either player 1 or player 2 cell");
	}
	drawText(stoneCount,TOP_LEFT.x + left,TOP_LEFT.y + top);
	}

view raw drawing.js hosted with ❤ by GitHub

Drawing the cell

The function itself is simple enough, simply calculating the position of the drawn elements based on whether we’re drawing for player 1 (top row) or 2 (bottom row). The text itself is the stone count.

Note also how we eliminate a magic number – the font number.

But a Cell Can Be Empty…

An acute reader should note that at this point we’re only drawing the text figures in cells. But updating the state of the board will require us to also remove the text, in case no stones are actually in the cell. This is a design choice – not showing a circle with a text (number of stones) in an empty cell; but it’s one we’re making for the sake of a nicer UI. We’d like an empty cell to be really empty, and not show ‘0’.

The next commit takes care of that. We add the code to essentially remove an existing drawing object. This leads us to the need to remember which UI objects belong to which cell. This is done by maintaining an array of canvas elements¹⁸ that correspond to each cell, when drawn:

	let stoneUIElement = [];
	…

	function initDrawingElements(cellCount)
	{
	range(1,cellCount).forEach( _ => stoneUIElement.push(None));
	}

	function rememberUIObj(boardCell,el) { stoneUIElement[boardCell] = maybe(el); }
	function forgetUIObj(boardCell) { stoneUIElement[boardCell] = None; }
	function uiObjAt(boardCell) { return stoneUIElement[boardCell]; }

view raw drawing.js hosted with ❤ by GitHub

Maintaining an array of UI canvas objects

Each element in the cell is an Option object ¹⁹ allowing to write more easily read code.

All that’s left to do is to keep track (“remember” and “forget”) the drawn elements, whenever we draw them. Of course, when the stone count is 0, we remove the canvas object, and “forget” it:

	function drawBoardState(cnvs,board)
	{
	…
	board.forAllCells(boardCell => {
	let stonesInCell = board.stonesIn(boardCell);
	switch (true)
	{
	case board.isPlayer1Home(boardCell) : drawOrRemove(boardCell,stonesInCell,(_,stoneCount) => { drawPlayer1Home(stoneCount); }); break;
	case board.isPlayer2Home(boardCell) : drawOrRemove(boardCell,stonesInCell,(_,stoneCount) => { drawPlayer2Home(stoneCount); }); break;
	case board.isPlayer1Cell(boardCell) \|\| board.isPlayer2Cell(boardCell):
	drawOrRemove(boardCell,stonesInCell,(boardCell,stoneCount) => { drawCell(boardCell,stoneCount); });
	break;
	default : ERR ("Invalid board cell when drawing state: " + boardCell); break;
	}
	})

	function drawPlayer1Home(stoneCount)
	{
	rememberUIObj(board.player1Home(),
	drawStones(stoneCount,
	TOP_LEFT.x + CELL_SIZE / 2 – FONT_SIZE/2-MARGIN,
	TOP_LEFT.y + CELL_SIZE * 1.5 – FONT_SIZE/2-MARGIN));
	}

	function drawPlayer2Home(stoneCount)
	{
	rememberUIObj(board.player2Home(),
	drawStones(stoneCount,
	/* left = /TOP_LEFT.x + boardWidthInCells(board.totalCellCount()) CELL_SIZE – CELL_SIZE/2 – FONT_SIZE/2-MARGIN,
	/* top = /TOP_LEFT.y + CELL_SIZE1.5-FONT_SIZE/2-MARGIN));

	}

	function drawCell(boardCell,stoneCount)
	{
	switch (true)
	{
	case board.isPlayer1Cell(boardCell) :
	… //calculating top,left
	break;
	case board.isPlayer2Cell(boardCell) :
	… //calculating top,left
	break;
	default : ERR("Invalid board cell: must be either player 1 or player 2 cell");
	}
	rememberUIObj(boardCell,drawStones(stoneCount,TOP_LEFT.x + left,TOP_LEFT.y + top));
	}

	function drawOrRemove(boardCell,stoneCount,drawFunc)
	{
	if (stoneCount > 0)
	{
	drawFunc(boardCell,stoneCount);
	uiObjAt(boardCell).ifPresent(uiObj => {uiObj.on('mousedown', _ => {dbg('Clicked cell: ' + boardCell + '!')})})

	}
	else removeDrawingAt(boardCell);
	}

	function removeDrawingAt(boardCell)
	{
	uiObjAt(boardCell).ifPresent(uiObj => {
	cnvs.remove(uiObj);
	forgetUIObj(boardCell);
	});
	}

	function drawStones(stoneCount,left,top)
	{
	… //create canvas objects and add them to the canvas
	//return the created canvas object
	}

view raw drawing.js hosted with ❤ by GitHub

Drawing and keeping track of canvas objects

Note that the drawStones function does the actual “drawing” – creating the canvas objects and adding it to the canvas, but it also returns the created object (a Group). This allows calling code to “remember” the object. I intentionally did not add the code to remember the objects in this function, since it would’ve made the function’s code more complicated – mixing separate concerns ²⁰. This way, there’s place in the code that does the drawing, and a place that does the accounting of the objects, each place operates at a different level of abstraction – the game board vs. the canvas objects.

Another thing to note is that regardless of the cell being drawn, the pattern of either drawing it or removing it is the same. The difference lies in how we calculate the coordinates of where to put it. We therefore create a single function – drawOrRemove – that encodes this repeating pattern. The function accepts another function – the drawFunc parameter – that does the actual drawing (calls drawCell or drawPlayer1Home, drawPlayer2Home). We could’ve chosen to abstract it differently – pass functions that simply calculate the coordinates. I eventually leaned towards this solution – a slightly higher abstraction (a function that draws the cell and not a function that calculates coordinates) thinking that I might want to alter the look and feel of different cells in the future.

One last thing to note in this part: when drawing the cell canvas objects, we’re already adding the mouse listener to respond to events (line 54 in the above snippet), at this point doing nothing except issuing a log message. We do this here since it’s the low level operation of attaching an event listener to the object. I’d like to maintain the rest of the code oblivious as much as possible to the details of the drawing objects.

Next, we’re going to look how the drawing will start responding to events, and what does that entail.