design-patterns-java: runnable GoF examples with a strict shape

An example for every pattern, and a demo you can run

The repository is part of the Refactoring.Guru project, and it contains Java examples for all the classic GoF design patterns. That is the whole scope, and it is a useful scope, because the value of a pattern catalogue is less in the code than in seeing the same idea applied consistently across many small situations.

The examples were written in Java 8 and also tested in Java 9, which tells you the vintage of the code. There is no framework, no build file to speak of and no dependency tree, which is the right choice for teaching material: a pattern example that needs a library to run teaches the library.

The way the examples are meant to be used is explicit. The README recommends working with them in IntelliJ IDEA, whose Community Edition is free, and after importing the repository you can run examples by right-clicking the Demo files inside every example and selecting Run from the context menu. So each pattern is a small runnable program rather than a snippet, and the reader sees the behaviour, not just the shape of the class diagram.

The roadmap in the README has two open items, and both are unchecked: adding detailed comments to all classes, and adding structure-only examples. The second is worth noting, because it describes an intention that is easy to misread. The current examples are deliberately runnable and concrete, and a structure-only variant, the class diagram without the behaviour, is a separate offering that is not there yet.

Importing the project, and the two ways to do it

The setup instructions are short, and they assume you will be running things inside an IDE rather than from a command line.

After downloading or cloning the repository, you import its root directory into a new project. There are two ways. Through the start dialog, you select the Import Project option and skip through the rest of the steps. Or through the main menu, the path is:

File > New > Project from Existing Sources...

Then, after the import, you can run examples by right-clicking the Demo files inside every example and selecting the Run command from the context menu.

The choice of IntelliJ IDEA over a plain text editor is a deliberate one, and the reason is worth stating. Each example is a small program, and the point of running it is to see what the pattern does. An IDE that indexes the project, resolves the imports between the sub-packages and offers a Run action on a class removes the two minutes of friction that otherwise stand between reading a pattern and understanding it.

The repository itself is minimal in the way a teaching repository should be. There is a src/ directory holding the examples, a README, a licence file and a gitignore. There is no build tool configuration to fight with, and no version matrix to satisfy, which is a relief when the goal is to open a file and read it.

The package convention is what makes the set navigable

The contribution guide is where this repository differs from a pile of example code, and the first rule is the package naming. Examples should match the package convention refactoring_guru.{pattern}.{example_name}, and the guide gives the example:

package refactoring_guru.factory_method.ui_example.buttons;

class Button {
...

Then there are four structural rules. Places classes into separate files. Groups classes into sub-packages, and the stated reason is practical, that it helps people understand the dependencies of a class by glancing over its imports. The second sub-package example shows the same thing again for the factory side:

package refactoring_guru.factory_method.example.factories;

import Button;

class Factory {
...

Read together, those rules mean every example has the same shape. A pattern directory, a set of sub-packages by role, one class per file, and imports that tell you which collaborator a class depends on. That consistency is what makes a catalogue of twenty patterns usable as a reference, because the reader learns where to look once and then applies that knowledge everywhere.

It also makes the examples diffable against each other, which is a subtle benefit: a reader who knows the factory method example can read the strategy example and notice the difference in one place rather than reading two unfamiliar trees.

Google style, 80 columns, and the reason for both

Two style rules head the contribution guide. All code should meet the Google Java Style Guide, and the code should be hard wrapped at the 80th character.

The second rule has a stated reason, and it is a publishing reason rather than a taste rule: it helps to list the code on the website without scrollbars.

That reframes the whole repository. These examples exist to be read on a web page, alongside prose that explains the pattern, and the 80-column limit is there so the code block fits the column. A style rule that exists to serve the medium is a rule you can follow without resentment, which is probably why the guide asks for it in a list of six numbered items rather than burying it in a formatter config.

The Google Java Style Guide reference does the heavy lifting for everything else, from braces to naming, and it means a reader who knows the guide can predict the shape of any file in the set before opening it.

The contribution process itself is deliberately frictionless. The guide asks for a fork, changes and a pull request, and says any help is appreciated, whether it is a typo fix or a whole new example.

The bilingual comments are a translation decision

The sixth rule is unusual enough to deserve a section of its own. Comments may or may not have language tags in them, and the guide gives this example:

/**
 * EN: All products families have the same varieties (MacOS/Windows).
 *
 * This is a MacOS variant of a button.
 *
 * RU: Все семейства продуктов имеют одни и те же вариации (MacOS/Windows).
 *
 * Это вариант кнопки под MacOS.
 */

And then the instruction that makes it work: don't be scared and ignore the non-English part of such comments. If you want to change a comment like this, feel free to do so, and even if you get it wrong, the maintainers will tell you how to fix it during the pull request.

The pattern here is that every example exists in an English version and a Russian version, side by side in the same comment block, because the project's readership is not English-only. The two languages are separated by an EN and an RU tag, and the code itself is the shared part.

This is a small piece of design that says something about the project. A catalogue of design patterns in Java is already a translation of the Gang of Four book into code, and doing it into two human languages at the same time is a further translation, and the guide treats that second translation as something to maintain rather than something to avoid.

Where the examples are the wrong thing to copy

The first wrong-tool case is production code, and the reason is the licence. The work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License. That permits reading, copying and redistribution with attribution, and it forbids commercial use and derivative works. A pattern catalogue you cannot use commercially is a different artefact from a library you can depend on, and the README is explicit about the terms.

The second is a modern Java codebase. The examples were written in Java 8 and tested in Java 9, so the idioms on display, records, sealed classes, pattern matching, are all absent. For a reader who already knows Java 17 or later, the value is in the pattern structure rather than in the language, and a team writing new code would translate the idea rather than copy the file.

The third is a project that needs a real design. These are teaching examples, small on purpose, and the guide's own roadmap acknowledges that the code is not yet thoroughly commented and that structure-only examples do not exist. The patterns are also known to be contested. A pattern applied because it is a pattern, rather than because the problem calls for it, is the mistake every catalogue in this genre invites, and a reference implementation is not an argument for using it.

The fourth is the multi-language pattern, which is worth a mention because the value of the catalogue is partly comparative. Reading the same pattern in two languages, in the two directories of the wider Refactoring.Guru project, is where the ideas generalise.

CC BY-NC-ND, two authors, and a repository that is still open

The project is licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License, with LICENSE.txt at the repository root and the licence badge at the end of the README. The repository is not archived, and the last push was on 2026-04-14.

There are no GitHub releases, and there is no version to pin, which is consistent with a repository whose artefact is a set of source files you read rather than a package you install.

The credits name two authors, Bohdan Herashchenko and Alexander Shvets, with their GitHub handles. That is a small detail, and it is worth noticing in a catalogue of this kind, because a list of patterns with two names attached is a set of decisions about how to structure a factory, which class owns which responsibility, and what the collaborators are called. Those decisions are as much the content as the code is, and they are the part a reader is most likely to copy by osmosis without noticing.

The style guide in the contribution file, the fixed package layout, the bilingual comments and the open pull request invitation add up to a project that is trying to stay consistent while accepting outside contributions, which is the only way a catalogue of this size stays useful over a decade.

Editorial conclusion

Adopt these examples as a study aid and as a reference for how each GoF pattern looks in idiomatic Java, and use the Demo classes to see the behaviour rather than to read it. Do not copy the code into a commercial product, because the licence is Creative Commons Attribution-NonCommercial-NoDerivatives 4.0, which forbids commercial use and derivatives. Before you build on any of it, read the contribution guide rather than the code, since the package convention and the class-per-file rule are what make the set navigable, and expect the examples to show Java 8 idioms written in 2020 rather than current Java.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. RefactoringGuru/design-patterns-java on GitHub