Skip to content

Commit f49c228

Browse files
Note on input validation and other distractions (#267)
* Note on input validation and other distractions * Apply suggestions from code review Co-authored-by: Donald Sebastian Leung <donaldsebleung@gmail.com> Co-authored-by: Donald Sebastian Leung <donaldsebleung@gmail.com>
1 parent 0b43449 commit f49c228

File tree

1 file changed

+2
-2
lines changed
  • content/authoring/guidelines

1 file changed

+2
-2
lines changed

content/authoring/guidelines/kata.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@ This article contains a set of guidelines, which can be used by authors to creat
1818
## Task and Requirements
1919

2020
- **Requirements and design should hold to generally accepted and widely recognized guidelines** related to software design, programming, and domain of the kata. Do not require users to do things in a way that is widely recognized as wrong. If any of these guidelines are broken, the description should justify it with a plausible explanation.
21-
- **Keep kata focused on one task.** Avoid distractions, do not add other, smaller, "side" requirements that do not add too much value to the task itself.
22-
- **Make requirements very clear.** If kata is not a puzzle, describe everything that will be tested and leave no surprises. The reason for every failing test case should be evidently visible in the description of the kata.
21+
- **Keep kata focused on one task.** Avoid distractions, do not add other, smaller, "side" requirements that do not add too much value to the task itself. Additional "steps" required to solve the task usually do not make the kata more interesting, but are rather seen as tedious and distracting. While things like validation of the input, parsing or stringification, filtering of invalid elements, etc. can be a part of some kata related to specific topics (for example, parsers or interpreters), usually they are just additional nuisance a user has to struggle with, and do not add too much value to the task.
22+
- **Make requirements very clear.** If the kata is not a puzzle, describe everything that will be tested and leave no surprises. The reason for every failing test case should be evidently visible in the description of the kata.
2323
- **Use ideas that can be easily translated,** if they are not the main point of the kata. It is generally OK to use code constructs idiomatic for the language of the author's choice, but be aware when such idioms can cause problems to translators. Sooner or later someone will translate the kata to another programming language, and if the translator is not able to efficiently handle the original, idiomatic approach, the quality or consistency of the translation can suffer.
2424
- **Do not use requirements which cannot be reliably tested, enforced, or expressed in terms of a kata.** Some requirements simply do not translate well into a kata, and code restrictions (_"Do not use X"_, or _"You have to use Y"_) is one example of such.
2525

0 commit comments

Comments
 (0)