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

This article applies to:

E-Prime 3.0

E-Prime 2.0

E-Prime 1.x

Detail

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.

Experiment Structure:

• Use descriptive names for objects (e.g., StimulusDisplay, MaskDisplay instead of the default - TextDisplay1, Slide1, etc).
• 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 participant 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 (see E-STUDIO: Unreferenced E-Objects [27730]).

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:

• 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.

• 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.

• 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.

Examples:

For more information, view the E-Prime Command Reference for specifics involving E-Basic (https://pstnet.com/ecr).