Creating your first kata

Kata on Codewars are created by regular users who want to share their ideas with the community and create challenges for others to train on. After solving a few kata, many users often find that they want to contribute back to the community with kata of their own. Not only can authoring a kata be a great learning experience, well-crafted kata are a source of great fun for everyone.

However, first-time authors – regardless of programming experience – may not realize that creating a good quality kata from scratch is a much more involved task than solving one, as it requires a wider mindset and broader set of skills (if that sounds intimidating, don't be discouraged: that's what this tutorial is for!). In many ways authoring a kata is closer to what would be considered a "professional" task: it requires designing a challenge with a diverse target audience in mind, implementing a solution, creating tests, handling feedback from users, and finally maintaining them. Every kata is like a small software product and goes through an equivalent of a full software development lifecycle.

Support for authors

To support you in this challenging task, we have provided some helpful resources:

• Tutorials for users new to the authoring process.
• Guidelines which must be respected in order to meet the Codewars quality criteria. It is strongly recommended becoming familiar with these, otherwise you risk receiving negative feedback on your newly created kata, including numerous issue reports and possibly harsh remarks.
• Recipes explaining how to solve frequently occurring tasks or work around common problems.
• Language specific pages that contain related code snippets, examples, references and tutorials.

You can also reach out to the community directly with any questions and seek experienced users' advice on our Discord in #help-author channel.

Requirements

In order to create a new kata, you first need to earn the "Create Kata" privilege, which is automatically awarded once you accumulate 300 Honor points. Then you can select the "New Kata" option from the profile menu:

How to create a good kata

While everyone enjoys an interesting and well-crafted kata, no one likes to struggle with poorly authored challenges. That said, it is often difficult to identify good and bad kata qualities and determine what sets them apart, especially for inexperienced authors. There are a few factors that have a drastic influence on the enjoyment other users will experience solving your kata and, as a result, the feedback it will receive.

Kata ideas and duplicates

At the time of writing, there are already ~7000 approved kata and over 2000 kata in beta status. With such a vast selection of kata, chances are high that your idea may not be unique - popular topics like FizzBuzz, Fibonacci numbers and Rotation Ciphers are virtually guaranteed to have been covered already.

The reason we mention this is that we don't need dozens of duplicate FizzBuzz kata. Whenever a kata is identified as a duplicate (and it usually will), it will be retired and thus effectively removed the kata catalog.

Here are a few steps to ensure users like the idea presented in your kata:

• Try to come up with a novel and original idea. Not only does this entail crafting a unique theme or backstory, but would ideally also involve a new, interesting approach to a problem. There are already many kata that cover a range of popular topics, including:
  • Basics for beginners, such as the Fibonacci sequence, FizzBuzz, factorials, etc.
  • Simple map/filter/reduce operations on lists or arrays. Numerous kata exist which merely require iteration over a sequence while selecting/transforming some of its elements based on simple criteria.
  • Calculating the result of a mathematical, physical, or chemical formula. Substituting values into a formula has also been done before.
  • Simple graph search algorithms like path finding, BFS, DFS, etc. have been covered sufficiently.
• Search for keywords to find out if someone has already done something similar. Not only basic topics have been extensively covered (Fibonacci numbers, factorials, FizzBuzz), even advanced topics such as Peano and Church numbers have multiple similar kata dedicated to them, as the search results clearly show.
• Solve more kata. Doing so will offer you a better overview of what kinds of kata already exist. Having solved your 13th Fibonacci problem will help you understand why duplicates are as unpopular as they are.

Kata quality

Even the best idea can be ruined by poor execution. Fortunately, there is a set of quality guidelines which, when followed properly, will ensure that all individual aspects of your kata will combine into a well-regarded experience. While it may seem like a lot to take in, do make a point of reading and understanding them, so you can apply them to your kata. Remember that whenever any problems or questions arise, you can always ask for help on Discord in #help-author channel.

Learning from experience

There's no better teacher than experience, which is why it's never a bad idea to solve more kata and learn from them. Doing so can help significantly in the following aspects:

• Gaining more experience will help you understand how difficult your kata is compared to others. This enables you to better tune your kata to the goals you have in mind.
• The more you train, the more familiar you will become with the most efficient solutions to a given problem. This is crucial knowledge for performance and golf kata: you can't author a performance kata without knowing a performant algorithm.
• Encountering and identifying issues and reading the discourse on other kata will reveal the most common issues users run in to. Learn from other people's mistakes.
• Studying solutions and, more importantly, solution comment sections will give you an insight into what constitutes good practice.
• Training on kata allows you to see how others write their tests. Writing good tests is hard, especially if the kata is (supposed to be) difficult. Look at the sample tests, but also take note of how submission tests are constructed and organized.
• By solving and reviewing beta kata you can see what other authors tend to get wrong, what mistakes reviewers commonly point out and how to best resolve them.

Be aware though that there are many old kata created a long time ago that do not hold up to the current standards. The poor quality of an existing kata is not an excuse to create a sub-par one yourself.

Setting up the kata

Kata are created with the kata editor tool as described in the Kata Editor reference. To fully set up the kata you must provide some basic information as well as code in the language(s) of your choice.

Kata Properties

Name

The name is used to uniquely identify a kata. You can be creative when choosing a name, however the best practice is to pick a name that informs users about the kind of challenge they can expect.

Discipline

The discipline is the category that the kata belongs to. You should pick the category that best describes what the kata is intended to focus on. As of now, there are five categories covering the following skill sets:

• Fundamentals - Core language and API knowledge.
• Algorithms - Logic required to complete the task.
• Bug Fixes - Analyzing existing code, identifying the issue, and fixing it.
• Refactoring - Rewriting and improving existing code.
• Puzzles - Extrapolating a solution from a limited set of information.

Estimated rank

This is where you specify how difficult you think your kata is. This value is used as an initial estimate for the kata's difficulty and will be refined by collecting rank votes from other users who solved it. Your perception of your kata's difficulty might differ from that of the community, so your kata may end up approved with a higher or lower rank than your initial choice.

Tags

Tags are used to classify your kata and make it easier to find via search. Some tags are derived from the assigned discipline and added automatically, but you can add more if you like.

Allow Contributors

You can allow other users to contribute and make changes to your kata while it undergoes the beta process. However, even when you do not allow contributors, certain users with sufficient privilege will still be able to edit your kata if it has pending issues or requires fixing.

You can check the list of privileges to see who can modify your kata.

Description

The description field is where you provide the information and instructions users require when training on your kata. This field recognizes GitHub flavored Markdown with a set of Codewars extensions. Use the Preview tab to see how it will look like when presented to users.

A kata's description is the first thing users see and forms the basis of their first impressions. A clear and concise description that covers all the necessary information encourages users to give the kata a try. By the same token, a user who finds the description lacking is likely to raise issues or downvote your kata.

The difficulty of writing a good description should not be underestimated, which is why you are strongly encouraged to refer to "Writing a Kata Description" guidelines to ensure that your description is of sufficient quality.

Code Snippets

Obviously, a kata needs some code to run. On Codewars your code is divided into individual snippets, each of which serves a specific purpose within the kata. Structuring the code this way also keeps the kata easy to maintain, which is why every snippet must adhere to both general and role-specific quality guidelines.

Complete Solution

You need to provide a solution to your own kata to prove that it is in fact solvable. The author's solution is run every time a kata is published in order to verify the correctness of tests and the general kata setup.

Initial Solution

The initial solution is the code users are provided with when they start training on your kata. How you set up your initial solution code will depend heavily on the discipline you selected. Bug-fixing and refactoring disciplines require the inclusion of a partially or fully working solution respectively within this block. For fundamentals and algorithm disciplines you will likely only include skeleton code, such as an empty function, class or other code that serves as a starting point for a user's solution. In some cases you may just want to include a few helpful comments to help get the user started, but no actual code itself.

Special care must be taken when providing code for the initial solution. You may have encountered a situation yourself where the provided initial solution was incorrect (e.g. code that wouldn't compile, function signatures that differed from the tests or description, etc.). Hunting down the required information in the description or sample tests is an exercise in frustration and, more importantly, a waste of time that should have been spent actually solving the kata.

The only time non-compiling code is acceptable is when it is an intrinsic part if the challenge, for example when the kata focuses explicitly on debugging or involves solving language-specific compile-time problems. In any other case, it is considered a kata issue if the initial solution does not compile. To avoid this, you must obviously supply some kind of placeholder code or "dummy" implementation which, depending on the chosen language, typically takes the form of a no-op or return statement. Note that this placeholder code only needs to satisfy the compiler, but may (and likely will) lead to run-time errors if not replaced by the user.

The same rule applies to interpreted languages (e.g. JavaScript, Python, Ruby): the initial solution must not contain syntax errors and/or (top-level) reference errors that prevent the user from immediately implementing their solution.

Examples:

// C#
public class Kata
{
    public static string RepeatString(string s, int n)
    {
        // Return the zero value so this compiles.
        return "";
    }
}

// C#
public class Kata
{
    public static string RepeatString(string s, int n)
    {
        // Return the zero value so this compiles.
        return "";
    }
}

# Python
def repeat_string(s, n):
    # Avoid syntax error with `pass`.
    pass

# Python
def repeat_string(s, n):
    # Avoid syntax error with `pass`.
    pass

Preloaded

The preloaded code block is an optional feature you can use if you need it. Code from the preloaded snippet cannot be edited by the user, but it is made available to all other snippets (solution and tests). For example, you might want to mimic an API that users should interact with from within your kata, or you need to supply predefined classes and constants that are available both to a user's solution and the tests, but need to be kept safe from modification by the user.

Working with preloaded code can be tricky, which is why we've created a set of guidelines related to this particular snippet.

Test Cases

The Test Cases editor is where you provide mandatory submission tests, against which a user's attempted solution is run and validated. Tests are not visible to the user, and a solution needs to pass all of them for the kata to be considered completed. Every programming language on Codewars is set up to include a testing framework that you can use to write, organize and group test cases, as well as provide assertions for tested conditions. You can find out which testing framework is available in the language of your choice by visiting the language's reference page.

Tests are a very important aspect of every kata. In fact, together with the description they play the most significant role in determining a kata's overall quality. Bad tests attract negative feedback and are a common cause of auto-retirement for beta kata. Well written tests, on the other hand, are highly appreciated by users training on a kata. Writing a good test suite requires a lot of thought and work, and commonly proves the most difficult aspect of kata creation – it often requires more code than the actual solution. Make sure to follow the quality guidelines for submission tests when writing them, as they will help you avoid many common pitfalls awaiting inexperienced authors.

The essential function of a test is to perform the following two tasks:

1. Accept all conforming solutions
2. Reject all non-conforming solutions

It may seem that point 2 is encapsulated implicitly in point 1, but this is not the case. Tests that allow both correct and incorrect solutions to pass are pointless. Properly constructed test suites accept all correct – and only correct – solutions and reject all others.

A comprehensive set of tests should cover all the following aspects:

• Test basic functionality
• Provide full coverage (or at least decent coverage, if that's not possible)
• Cover edge cases thoroughly
• Generate randomized tests to probe user solutions with random samples and prevent pattern-matching
• Test for performance, code characteristics or other restrictions specific to your kata's design.

Of the above aspects, the first three should be covered by fixed tests, which are static tests you design manually and are repeated each time a solution is attempted. The last item is optional and it is left to you to decide how you implement such tests (randomly or designed specifically for that purpose).

Random tests are test cases that cannot be predicted by the user as they are generated differently each time the test suite is run. They are a critical component of good test design, which is why most kata (except for very old ones) implement them, ideally in combination with fixed tests. Using both static and random test cases help users see what they are supposed to do, as well as make it impossible to pass your kata by simply analyzing inputs and expected outputs and hard-coding them into a solution. Random tests also supplement fixed tests by increasing the odds of generating edge cases you may have overlooked.

When a solution fails a test and the user wants to identify and correct their mistake, they need to know:

• the input
• the expected and actual results

So unless revealing the expected result would spoil the kata, you should not withhold it. Consult the documentation of the testing framework used by your language and pick the best method for your tests.

Example Test Cases

Example test cases are a small sample of tests that the user can see and modify while working on their solution. They are automatically loaded into the Sample Tests section when a user begins training on a kata. Just like submission tests, example tests utilize the testing framework of the chosen language.

Except in circumstances where providing sample tests to the user would spoil the kata (see Defuse the bombs for an example), they are considered a requirement, since they provide users with a clear understanding of the way their solution will be tested and needs to behave. The easiest way to include sample tests is to simply copy over a few fixed tests from the full test suite. It is considered a kata issue if sample tests are not included unless strong justification for their absence can be provided.

Since sample tests can significantly impact a user's experience of a kata, they have a dedicated set of sample test authoring guidelines.

Before publishing

When you have finally written all the code, prettified the description, and verified the tests, you'll probably consider your kata good to go. But this is a very good moment to take a step back and hold off on publishing your kata, at least for a short while. It's possible you were focused so hard on writing your kata that you ended up missing some issues or possible improvements. Take your time ensuring your kata is truly ready to be published; while minor issues are expected during the beta process, if users find too many problems that you have overlooked, you risk your kata being downvoted or, in the worst case, instantly retired.

Train on your kata

A good first step is to train on your own kata. Taking the place of a potential user is a great way of checking what others will experience while solving your task. Although a Kata in Draft status cannot be completed, it's still possible to train on it. Just open your kata in the trainer and try to solve it as any other user would do. This way, you might spot problems with the tests or initial solution that you previously missed.

Verify quality guidelines

The next step should be to read through the authoring guidelines again, using them as a checklist to verify that your kata conforms to the applicable rules. Remember that the guidelines were collected based on the community's experience with many poor quality kata published back in the early days, so take them seriously and approach them with proper attention. If you do not understand a guideline, or you are not sure whether your kata violates it, join our Discord to ask more experienced users for advice in #help-author channel.

Ask for a review of your draft

Kata in draft status are not listed and cannot be searched for, however users with direct links can still access them. You can share the link with others in #help-author channel on our Discord and they will be able to read the description, train on the kata, and provide feedback, before getting a chance to rate it. This is a great way to get quick feedback about the most obvious problems while you're working out the kinks.

After publishing

After you publish your kata, it becomes subject to the beta evaluation process. At this point, power users will immediately jump on it, knowing they will find problems, the discourse section will be flooded with issue reports and, unless you managed to avoid any serious issues, the satisfaction rating might start to drop. This may be discouraging at first, especially for first-time authors, but it is also to be expected; after all, no one wants an unfinished kata to get out of beta, right? That's why it is so important to make sure that when your kata is published, it's already in as good a shape as possible.

That said, no matter how hard you try, you can never satisfy everyone. Even if your kata receives overwhelmingly positive votes, some users might still not like it. Do not worry about this too much, but do not disregard their feedback either. Give their remarks some consideration, they may point out ways in which your kata can be improved. Listen to everyone, answer their questions, consider suggestions, and fix any issues that crop up. Also, do not rush things too much. If someone says something you are not sure about, just wait for another opinion. Then again, users tend to disagree a lot, and so might offer contradicting suggestions. It can be difficult, but in such cases you need to either find a compromise or just pick one option over the other and move forward. Your mindset and approach to the beta process matter: experience shows that kata whose authors engage actively and constructively in the process tend to graduate out of beta quite quickly, whereas other kata get retired within minutes, or, perhaps worse, never leave beta status due to the author's unwillingness to accept advice or fix issues.

Over the course of the review period, your kata might get automatically unpublished after collecting a certain amount of issues. Automatic unpublishing is not the end of the road for your kata. While back in draft, take note of the issues and fix the underlying problems in your kata. Once you've implemented those, you can resolve the issues and re-publish. For more details on the auto-unpublish feature see description of the beta process.

After your kata is published and gains a few completed solutions, it is likely that someone will translate it to another language for you. This is great, but do not get too excited about this just yet. It's recommended to give the original version some time to "settle down", mature and give the inevitable teething issues a chance to be identified before you start approving new translations. When a design issue with your kata is reported that necessitates some form of change, approved translations can get in the way and increase the maintenance effort. High maintenance cost is something you want to avoid at the early stage of a kata, when it's expected to change a lot.

After the kata collects enough positive feedback, it leaves the beta phase and becomes available for everyone to train on and earn their points. Now it will draw even more attention, and potentially thousands of users will submit their solutions, possibly finding new problems, reporting issues, and raising suggestions. Your task, as an author, is to actively maintain your kata. This will encourage more users to train on it, provide translations to other languages, and enjoy it to its fullest extent.

Congratulations! You've completed the tutorial. Your first Codewars kata is bound to be a smashing success! And don't forget: the Codewars community is here to help you out whenever you need.