Text Format for Exercises

Property names are simply words that start at the beginning of a line, followed by a colon.

The corresponding value follows the colon, and extends up to the beginning of the next property (any leading/trailing white space is trimmed).

Property order doesn't matter.

PropertyName: Some value goes here.

AnotherProperty: This value spans
multiple lines.

You don't have to start the value on the same line as
the property name. Instead, the value extends to the
start of the next property.

Most exercises start off with some common information.

The title does not have to be unique, but it should be both descriptive and concise. Often, it is like a method name, naming the method the student will write. If it is too long, it won't look nice when showing compact lists of exercises.

Language is just a textual tag indicating the programming language that is the focus of the question. Use a comma-separated list if the question applies to multiple languages.

The topics are just a comma-separated list of topic keywords or tags. Try to be consistent with the tags you use. [ToDo: provide a link to a tag cloud as a reference.]

The stem is the main textual content of the exercise, describing the problem to be solved. Here, it is shown using Markdown syntax.

Title: teenSum

Language: Java
Topics: if, condition, plus, integer

Stem:
Given two `int`s, _a_ and _b_, return their sum.
However, "teen" values in the range 13..19, inclusive,
are extra lucky. So if either value is a teen, just
return 19.

For single-answer multiple-choice questions, add a "Choices" property where you use a Markdown list (a numbered list) to indicate the possible choices.

Mark the correct choice by beginning it with "[correct]" (or "[1]"). Case doesn't matter.

You can use Markdown formatting in the answer choices, if desired.

Choices can span multiple lines and be as long as necessary.

Title: not operator

Language: Java, C++, C#
Topics: condition, not, boolean

Stem:
Which operator is used to represent logical negation
in a boolean expression?

Choices:
1. &&
2. ||
3. -
4. [correct] !

You can use "Explanation" to define an overall explanation that will be shown when someone answers the question.

A top-level explanation is shown if the exercise is answered incorrectly.

Choices:
1. &&
2. ||
3. -
4. [correct] !

Explanation:
Logical negation is expressed using the exclamation
mark as a unary operator in boolean expressions.

An "Explanation" can also be added to individual incorrect choices, and will be shown if the corresponding choice is selected.

You can also specify a numeric (0.0-1.0) value for a specific choice in the square brackets at the start of a choice, instead of "[correct]". In fact, "[correct]" is simply a synonym for "[1.0]", meaning full credit is earned for selecting that answer.

Partial credit may be specified by using values less than [1.0] in front of a choice.

Choices:
1. &&
   Explanation: The && operator represents logical AND.

2. ||
   Explanation: The || operator represents logical OR.

3. -
   Explanation: The - operator represents subtraction,
   and can also be used to represent a negative number.
   It is not used in logical expressions.

4. [1] !

Explanation:
Logical negation is expressed using the exclamation
mark as a unary operator in boolean expressions.

For code writing questions, instead of "Choices", one provides sections labeled "Code" and "Tests".

The "Code" section serves as a single place to provide the code the student sees, a sample (reference) solution, and the surrounding wrapper/scaffolding needed to compile the student's answer.

In this example, the student is asked to write a method called factorial(), and is given the just the method signature and outer braces to start with.

Title: factorial

Language: Java
Topics: if, condition, factorial, recursion,
        math, multiplication

Stem:
Write a function in Java called `factorial()` that
will take a positive integer as input and returns
its factorial as output.

Code:
public class Answer
{
    \show[
    public int factorial(int N)
    {
        \[
        if (N <= 1)
        {
            return 1;
        }
        else
        {
            return N * factorial(N - 1);
        }
        ]\
    }
    ]\
}

Tests:
tests {
    example tests {
        factorial(1) is 1
        factorial(3) is 6
        factorial(5) is 120
    }

    factorial(0) is 1
    factorial(2) is 2
    factorial(4) is 24

    hidden tests {
        factorial(6) is 720
    }
}

Code appearing inside \show[...]\ markers is taken as the starter code, used to populate the editor when the exercise is first visited or when it is reset. Multiple \show regions can be used, if needed, but there is usually only one.

Code:
...
    \show[
    public int factorial(int N)
    {
        ...
    }
    ]\
...

Code appearing inside \[...]\ markers is never visible to students, and serves as a way to provide a reference solution, or to demark multiple blanks where students can enter code. The "insertion point" of the editor when the student visits an exercise is the start of the first \[...]\ region (the first "blank"). Typically, there is at least one blank, although there can be more.

Don't omit the blank, or the entire \show area will be read-only!

Code:
...
        \[
        if (N <= 1)
        {
            return 1;
        }
        else
        {
            return N * factorial(N - 1);
        }
        ]\
...

Code appearing outside the first \show[...]\ region is taken to define the wrapper that is used to surround the student's answer.

Code:
public class Answer
{
    \show[
    ...
    ]\
}

If no wrapper is specified (i.e., the whole "Code" section is surrounded in \show[...]\), then the wrapper defaults to an empty public class called Answer.

Code:
\show[
public int factorial(int N)
{
    \[ ]\
}
]\

If no \show[...]\ is specified at all, it is assumed to surround the entire "Code" section, meaning the default empty Answer class is used as the wrapper (a shorthand for writing \show[...]\ at the top level surrounding everything).

Code:
public int factorial(int N)
{
    \[ ]\
}

Simple test cases for methods that behave like functions can be written in CSV form.

This format requires at least two columns, where the first contains the input parameter(s), and the second contains the expected result.

This example shows three test cases for factorial(). The first line represents a test that factorial(1) == 1. The second represents factorial(3) == 6. The third represents factorial(5) == 120.

By default, CodeWorkout will build a test description from the input and output values that looks like this:

factorial(3) -> 6

Tests:
1,1
3,6
5,120

An optional third column an be used to indicate example/hidden/static/screening status.

"Static" tests allow checking of simple structural/textual properties of solutions. The first (input) column specifies the pattern to check for, and the second (expected output) column specifies whether the pattern is required or prohibited. Static tests often are also "screening" tests, which means answers will only receive credit if the test passes (otherwise, the diagnostic is presented similar to a compiler error). In the example to the right, Examples of static checks include:

keyword: return
keywords: if, switch, else
class: Math
classes: List, ArrayList, LinkedList
method: toString()
methods: parseInt(), nextInt(), valueOf()
loops        // same as keywords:for,while,do
lists        // same as classes:List,ArrayList,LinkedList
maps         // same as classes:Map,HashMap,TreeMap
sets         // same as classes:Set,HashSet,TreeSet
arrays       // same as /\[[\]]*\]/

The result/output of a static check can be specified in these ways:

required
prohibited
present  // same as required
absent   // same as prohibited
true     // same as required
false    // same as prohibited
2        // required exactly 2 times
{1,3}    // must occur 1-3 times
{2,}     // must occur 2 or more times
{,3}     // must occur no more than 3 times

Tests:
loops,prohibited,static:screening
1,1
3,6
5,120

The third column can also be used to provide a custom description that will be shown in place of the default description when showing the test to students. (Note: hidden tests don't need descriptions, since they would never been shown.)

An optional fourth column can be used to provide an "explanation" shown when a test case fails.

An optional fifth column can be used to specify a test case weight. By default, test cases all have a default weight of 1.0. Weights are used to compute the weighted average of test case results for scoring.

loops,prohibited,static:screening
1,1,example
3,6,example
5,120,example: with a custom description
0,1
2,2
4,24,another custom description
6,720,hidden