Test- and validation guidelines

[jddingemanse]

Great if you want to test and/or validate materials produced by awtiCode participants! We have made some guidelines that you can follow. For the remainder of this announcement, it will simply be called testing.

What to test

There are basically three types of materials you can test:

• Jupyter Notebooks (.ipynb files): tutorials or classroom materials, available in the folder /notebooks;
• Code scripts (.py files): available in the folder /code
• Parts of the awtiCode package: available on the separate repository jddingemanse/awtiCode, but testing preferably happens by trying to install and use the package in your own Python IDE (e.g. Spyder or Jupyter Notebook).

What to look for during testing

You can follow the below steps as a checklist during testing.

1. Data

If any data is used in the example:
1.1 Is the data available in the folder /data, OR is it clear how a user can get the data?
1.2 Is the data real data? Real data is preferred over fake data.
1.3 Is the data not unnecessarily large? For the material to work as example, a small data file can be sufficient. A small part of a large data file is preferred over a large data file.

2. Code

2.1 Are variable names clear and instructive, and not too long?
2.2 Is the code structured and in a logical order?
2.3 Are different parts of the code explained with short comments (in case of a .py file), or with clear text (in case of .ipynb)?
2.4 Content of the code: is it clear what the code should do?
2.5 Content of the code: is the implementation of any mathematics / assumptions / methods correct? For this, it might be necessary to shortly explain some method in the code itself, and/or refer to a longer explanation in a GitHUB discussion or (later to be produced) documentation).
2.6 Does the code work / can you get it to run?

3. Functions

A specific type of code are functions. This is the case with the awtiCode package: code is organized in different functions under different modules. But also in some other code you might find defined functions. Apart from the above mentioned checks, for functions specifically you can check:
3.1 Is it clear how to use the function?
3.2 Are argument names clear and instructive - and not too long?
3.3 Is there a docstring (is there some text that appears when you put the functionname in help(...)), and is the docstring clear?
3.4 Does the function work?

How to share your test results

If you have tested some material that somebody else already described in a Discussion or Issue topic, you can reply on that same topic with some remarks resulting from your testing. However, if there are real problems with the material (it does not work for you, or it is not clear enough), you can create a new Issue, in which you explain the problems.

• If it is about a notebook or .py file, put your remarks on this repository (awtiCodeDev);
• If your remarks are about part of the awtiCode package, then put it as an Issue on that repository jddingemanse/awtiCode.

IMPORTANT: testing should be constructive. If you found a problem, try to come up with a solution yourself, and suggest that solution while you raise the problem.

If we missed any guideline, or you have a remark or question concerning any of the guidelines, you can reply to this announcement.