implementing-a-concept-exercise.md

How to implement a Swift concept exercise

This document describes how to implement a concept exercise for the Swift track.

Please please please read the docs before starting. Posting PRs without reading these docs will be a lot more frustrating for you during the review cycle, and exhaust Exercism's maintainers' time. So, before diving into the implementation, please read the following documents:

• The features of v3.
• Rationale for v3.
• What are concept exercises and how are they structured?

Please also watch the following video:

• The Anatomy of a Concept Exercise.

As this document is generic, the following placeholders are used:

• <SLUG>: the slug of the exercise in kebab-case (e.g. calculator-conundrum).
• <NAME>: the name of the exercise in PascalCase (e.g. CalculatorConundrum).
• <CONCEPT_SLUG>: the slug of one of the exercise's concepts in kebab-case (e.g. anonymous-methods).

Before implementing the exercise, please make sure you have a good understanding of what the exercise should be teaching (and what not). This information can be found in the exercise's GitHub issue.

To implement a concept exercise, the following files must be added:

languages
└── swift
    ├── concepts
    |   └── <CONCEPT-SLUG>
    |       ├── about.md
    |       └── links.json
    └── exercises
        └── concept
            └── <SLUG>
                ├── .docs
                |   ├── instructions.md
                |   ├── introduction.md
                |   ├── hints.md
                |   └── source.md (required if there are third-party sources)
                ├── .meta
                |   |── config.json
                |   |── design.md
                |   └── Example.swift
                ├── Package.swift
                ├── Sources
                |   └── <NAME>
                |       └── <NAME>.swift
                └── Tests
                    |── LinuxMain.swift
                    └── <NAME>Tests
                        |── XCTestManifests.swift
                        └── <NAME>Tests.swift

Step 1: Add code files

The code files are track-specific and should be designed to help the student learn the exercise's concepts. The following Swift code files must be added:

Add Package.swift file

Purpose: The project file required to build the project and run the tests. This file will be generated by swift package manager and should not need modification.

Add Sources/<NAME>/<NAME>.swift file

Purpose: Provide a stub implementation. This file will be generated by swift package manager and will need modification.

• The stub implementation's code should compile. The only exception is for exercises that introduce syntax we want a student to define themselves, like how to define a class or property. In this case, insert a descriptive TODO comment instead of providing stub code ).
• Stub methods and functions should throw a fatalError("<method name> not implemented") error. The message is subtly different for stub type methods and should include the static or class keywords in the message .

For more information, please read this in-depth description, watch this video and check [this example stub file][example-stub-file].

Add Tests/LinuxMain.swift file

Purpose: A file required to run the test suite on Linux. This file will be generated by swift package manager and should not need modification.

Add Tests/<NAME>Tests/XCTestManifests.swift file

Purpose: A file required to run the test suite on macOS. This file will be generated by swift package manager and should not need modification.

Add Tests/<NAME>Tests/<NAME>Tests.swift file

Purpose: The test suite to verify a solution's correctness. This file will be generated by swift package manager and will need modification.

• XCTest is used as the test framework.
• All but the first test should be skipped by default.
• Test methods must be named using lowerCamelCase, with the name of the test begining with test.
• Test methods may have multiple assertions, but must be written so that only a single assertion may be tripped per test.
• Test methods must not use force unwrapping of optional values.
• All of the tests must be added to the type property allTests.

For more information, please read this in-depth description, watch this video and check [this example tests file][example-tests-file].

Remove README.md file

This file will be generated by the Swift Package Manager, but it needs to be removed as it conflicts with a README.md file that will be generated for the student when they attempt the exercise.

Add .meta/Example.swift file

Purpose: The idiomatic example implementation that passes all the tests.

For more information, please read this in-depth description, watch this video and check [this example file][example-example-file].

Note that all of the above files except for .meta/Example.swift can be created automatically by running swift package init --type library --<NAME> inside the <SLUG> directory.

Step 2: Add documentation files

How to create the files common to all tracks is described in the how to implement a concept exercise document.

Step 3: Update list of implemented exercises

• Add the exercise to the list of implemented exercises.

Step 4: format code

All Swift code should be formatted using the swift-format tool. Swift-format is also available for macOS and Linux via Homebrew.

To run swift-format, open a command prompt in the directorycontaining the file you wish to format and then run:

• swift-format format -i <file-name>.swift.

To just check the file for errors, but not reformat it, run swift-format lint <file-name>.swift instead.

Step 5: Add analyzer (optional)

Some exercises could benefit from having an exercise-specific analyzer. If so, specify what analysis rules should be applied to this exercise and why.

Skip this step if you're not sure what to do.

Step 6: Add representation (optional)

Some exercises could benefit from having an custom representation as generated by the Swift representer (yet to be written). If so, specify what changes to the representation should be applied and why.

Skip this step if you're not sure what to do.

Help

If you have any questions regarding implementing the exercise, please post them as comments in the exercise's GitHub issue.