INFO: E-Basic Style Guidelines/Recommendations [17912]

The following stylistic guidelines are strongly encouraged when creating E-Prime experiments and writing E-Basic script. These guidelines help make your experiment's structure and script more readable (and thus, understandable) to users who are not familiar with your specific task.

When using a Slide object, use descriptive names for Slide sub-objects (e.g. Fixation, LeftPic, RightPic instead of the default - Text1, Image1, etc).

Give InLine objects names that describe what the code contained within them does (e.g. CalculateBlockAccuracy instead of InLine1).

Use a BlockList - TrialList structure even if only one block of trials will be run.

Include a "Welcome" screen at the start of the experiment to briefly introduce the subject to the task.

Include a "Goodbye" screen at the end of the experiment to let the participant know that the experiment has concluded successfully.

Cleanup unreferenced objects when development is complete to reduce the amount of script necessary to generate the experiment.

E-Basic Script:Variables

Constants should be in upper case with an underscore separating breaks in words (e.g. MAX_LEVELS, NUM_PRACTICE)

Use a common and consistent naming convention when naming variables. A common naming convention used in Windows programming is called "Hungarian Notation" and encourages the use of common prefixes indicating a variable's type:

Variable Type

Prefix

Example

String

str

strText

Long

n

nDuration

Integer*

n

nOffset

Double

dbl

dblRefreshRate

Boolean

bool

boolCriteriaMet

Array**

arr, the

arrMyIntegers, theIntegerArray

E-Basic Objects

the

theResponseObject, theResponseData, theDisplayCanvas

* - Users are encouraged to use Long instead of Integer in EVERY case EXCEPT those where an integer is required (i.e. function calls or where byte math is necessary).

** - For arrays, use EITHER arr or the, not both.

In addition to using a consistent naming convention, attempt to use descriptive names for variables. Naming a variable 'x' tells you very little about what the variable holds and what the variable is used for. Naming a variable 'nResponseCount' tells you everything you need to know about the variable. Descriptive variable names are especially important in loops. Do not be afraid to use long variable names! They make your code much more readable.

Attempt to use the Long data type instead of Integer. An Integer can only hold up to 32767, while a Long can hold up to 2 billion. By using Long, you curb the possibility of an overflow error in your experiment.

Use the g_ prefix when naming global variables (e.g. g_strText)

When declaring variables, use only one Dim statement per line.

Avoid using the Variant data type if possible.

Objects

When accessing an E-Object via script, use the RteRunnableInputObject data type and the Rte.GetObject function. For example: Set theResponseObject = CRteRunnableInputObject(Rte.GetObject("StimulusDisplay")). You can then reference the StimulusDisplay object in script using theResponseObject. For example: nResponseCount = theResponseObject.InputMasks.Responses.Count. This increases your script portability. If the script is transferred to another experiment where the response object is named something other than StimulusDisplay, you will only need to change the object name sent to the Rte.GetObject function, rather than changing the object name every single time the object is referenced in script.

When assigning a variable using the Set statement (e.g. Set theObject = StimulusDisplay), the next line of code should be If Not theObject Is Nothing Then... to ensure the previous fuction returned a valid reference. For example, if Set theMouseResponseData = CMouseResponseData() is used on a keyboard response, the value returned would be "Nothing". Without using If Not theMouseResponseData Is Nothing, a run-time error may occur.

At the end of any subroutine, function, or InLine, use Set theObject = Nothing to ensure proper reference counting. This is especially important for the Canvas object and any display objects.

When processing responses, use the Object.InputMasks.Responses collection, which provides a union of all responses collected by the object. This results in script that can be more easily transferred between experiments (using Object.InputMask(1), for example, does not.

When enumerating through responses, attempt to use the generic ResponseData object, then use the specific KeyboardResponseData or MouseResponseData when the exact type is necessary.

Style

Indent code contained within If..Then statements, Select..Case statements, Do..While loops, For..Next loops, etc. This makes your code much more readable and makes it easy to determine when particular blocks of code are executed and what they do. Blocks of code can be indented or outdented in E-Prime by highlighting the block of code you wish to indent/outdent and pressing Tab or Shift+Tab, respectively.

Heavily comment everything you do. What your script does may be obvious to you, but may not be to someone unfamiliar with your task. Explain why variables are being declared and what they will do, explain why you are assigning particular values to variables, explain what conditional statements and loops are doing, and so on. Variables and subroutines should have ample comments to describe what they do and preferably where they do it or are called from. Place comments on the top of code versus to the right or below it.

Use mixed case when writing code, particularly when using reserved words in E-Basic. All upper or lower case should be avoided. For example, If intCounter = 1 Then instead of IF INTCOUNTER = 1 THEN.

Use Debug.Print statements when possible, especially immediately before the script is throwing an error to gather more information about the possible cause of the error or to assess precisely where the error is occurring. Use the Debug.Assert statement throughout your script to ensure programming integrity.

When concatenating strings, use multiple lines instead of keeping the entire concatenation on a single line.

'If the assert below fires, then the object named in the line above does not exist.Debug.Assert Not theResponseObject Is Nothing

'Counter variable for the number of mouse responses madeDim nClickCount As Long

'Counter variable used in for loop.Dim nIndex As Long

'Enumerate through the responses collection and determine'if any of the responses were made by the mouse.For nIndex = 1 To theResponseObject.InputMasks.Responses.Count

'Set theMouseResponseData equal to the current mouse response 'If the response was not a mouse, then the CMouseResponseData 'cast/conversion will return "Nothing"Dim theMouseResponseData As MouseResponseDataSet theMouseResponseData = CMouseResponseData(theResponseObject.InputMasks.Responses(nIndex))