Table of contents

1. Introduction
2. Naming
3. Use of names/tags/labels
4. Use list definitions
5. Formatting
6. Dealing with large questionnaires

Introduction

Coding style is very personal but please at least consider the points made here. They are intended to make DSC files easier to read and maintain.

Following conventions can also make it easier to write a DSC - you don’t need to think about how to name things, you just follow the rules. Having said that you will find that not all the examples in this Knowledge base have followed the conventions recommended here. :)

Naming

Question identifiers in upper-case - e.g. A1, B1, Q1.

With the exception of question identifiers, use lower-case, and separate words with an underscore.

List identifiers (DEFINITIONS) should have the prefix "lst_" and either the identifier for the question(s) (e.g. lst_A1, lst_A1A2) or a meaningful name (e.g. lst_gender, lst_satis).

List variables used with SETQLIST/SETQARRAY should use the prefix "items_" and the question it will be used for - e.g. items_A1, items_B1

"iterator" variables (FOREACH iterator IN list) should use the "i_" prefix and the name (without the “lst_” prefix) of the list type - e.g. i_A1, i_gender

Back to start

Use of names/tags/labels

Firstly, a quick reminder (more details here) that list items are defined as:

NAME [(TAG)] [LABEL]

Both TAG and LABEL are optional, and will default to the name if not declared in the DSC file.

Legal combinations are:

• NAME - TAG and LABEL are both imputed to be the same as NAME

• NAME LABEL - TAG is imputed to be the same as NAME

• NAME (TAG) - LABEL is imputed to be same as NAME

• NAME (TAG) LABEL

In your questionnaires, either use meaningful names (yes, no, male, female etc) or no names at all - i.e. use the “tag” value instead of the name.

e.g.

lst_gender = { male (M) “Male”, female (F) “Female” }

or

lst_sector = { 1 “Private sector”, 2 “Public sector”, 3 “Non-profit / charity”, 4 “Other”, 5 “Not applicable” }

Back to start

Use list definitions

You should use list definitions as much as possible. Whilst this can be less convenient as the definition of a question is split into two different parts of the DSC, it is required in order to use the list manipulation functions (you need to define variables using the same list definition), and also encourages you to share list definitions across questions.

Formatting

• Indent with two spaces. Normal advice would be to use larger indenting, but due to the lack of user-defined functions in the CAWI, it is sometimes unavoidable to have deep levels of indenting.

• Any statement (e.g. NEWPAGE(), BEGINCANVAS()) that has a corresponding closing statement should have the contents indented.

• Do not indent the main sections of the DSC (DEFINITIONS, QUESTIONS, VARIABLES). This adds an extra level of indenting to almost every line in the DSC, without any value (you can normally tell which section you are in based on the contents).

• Include files should have the ".inc" extension. Only the "top-level" DSC file should use .dsc

• Include question attributes (e.g. @[qnotes=...]) on a separate line at the end of the question, unless the entire question definition can fit on a single line.

• Opening braces should be the last character on the line, and closing braces should be on a line of their own, unless the same starement continues (e.g. "} ELSE {").

IF (q1 == 3) THEN { DO_SOMETHING() } ELSE { DO_SOMETHING_ELSE() }

Back to start

Dealing with large questionnaires

For "large" questionnaires built from multiple modules, use include files and arrange as in the example below (assumes two modules called a and b):

DEFINITIONS //common definitions

QUESTIONS //common variables - qstatus, version etc

//The questions for each module in separate include files @<"Q_a.inc" @<"Q_b.inc"

VARIABLES //common variables

ROUTE //standard opening questions

//The routing for each module in separate include files. @<"R_a.inc" @<"R_b.inc"

Each "Q_*.inc" file can include its own DEFINITIONS, QUESTIONS and VARIABLES sections, which are applicable only to that module. The scripting language allows multiple DEFINITIONS, QUESTIONS and VARIABLES sections.

To aid testing you can optionally include a "modules" question to control which modules are asked when testing. Implement at the top level of the route section as in the example below:

QUESTIONS modules "Which modules do you want to test" :{moda,modb,modc} {*} @<"Q_a.inc" @<"Q_b.inc" @<"Q_c.inc"

ROUTE NEWPAGE() ASK(modules) ENDPAGE() IF (modules IN {moda}) THEN { @<"R_a.inc" } IF (modules IN {modb}) THEN { @<"R_b.inc" }

Note: If questions in a module depend on questions asked in a previous module then this has to be dealt with by the program. For example suppose modc depends on answers in moda then use:

IF (modules IN {moda,modc}) THEN { @<"R_a.inc" }

Or else ask the relevant moda questions at the start of modc inside a condition the ensures they are only asked in test mode.

Back to start