VPin Workshop Table Script Formatter 0.2.1-alpha

GitLab repository: https://gitlab.com/PDStig/vpin-workshop-code-formatter

Here is a simple utility to help you format your table code according to the coding standards of the VPin Workshop. This is still in development, so not all formatting tools have been implemented or thoroughly tested yet.

This utility is not a magic solution for everything; you will likely need to make additional manual edits to your script to make it fully compliant with VPW standards. However, this utility will do 90% of the work for you.

Choose which formatting operations you wish to perform (disabled switches are coming soon):

VPin Workshop Coding Standards:

• Indentations Fix Indentations
  • Use a single tab for each level of indentation. Do not use spaces.
  • Increase the level of indentation of code within blocks according to the context of the code / code blocks:
    • Class, Sub, Function, If/Else/ElseIf, loops, With, Select Case, Property Let/Get/Set, etc.
    • Each Case within a Select Case should also have an indent, as so the code within that case, to make reading cases easy.
    • Pro Tip!: You can increase the indentation on an entire block of code at once by selecting it and pressing Tab. You can decrease the indentation by using Shift+Tab on your selected code block.
  • Example:
• Spacing
  • Add one space before and after arithmetic or logic operators. Add arithmetic whitespace
    • Examples: 3 + 5, myVar <= 3, myVar > -4, 6 + (5 * 3), myVar = "newValue"
  • Add one space after each comma in a list (e.g. defining an Array) or in parameters. Add space after commas
  • Within a pair of braces, do not add a space after the beginning brace (([{) nor add a space before the ending brace ()]}). Remove unnecessary whitespace
  • Do not add a blank line after the start of a code block or before the end of a code block (Sub, Function, Class, loop, If/Then, With, Property, etc.). Remove unnecessary blank lines
  • Have one blank line at the end of the table script and every vbs file used to make it easier to add code at the bottom later. Optional Requires manual editing
• Capitalization
  • Capitalize and camel-case all VBScript native keywords, constants, and methods. Fix capitalization
  • Capitalize and camel-case all global VPX variables and methods. Fix capitalization
  • Ensure consistent capitalization between all defined Dims, Consts, methods, etc. and references / calls to them throughout the code. Requires manual editing (for now)
  • Capitalize and camel-case all VPX table elements. Optional Requires manual editing
  • Ensure correct capitalization for non-globals according to the VPX CommandReference.txt. Requires manual editing
  • To distinctly separate constants from variables, use the names of constants in all caps, and use underscores _ between each word. Optional Requires manual editing
    • Example: Const THIS_IS_A_CONSTANT
  • To distinctly separate variables (Dims) from methods / routines / globals / table elements, start variable names with a lower-case letter and methods / routines / globals / table elements with a capital letter. Optional Requires manual editing
• Braces
  • Do not use parenthesis when calling a sub unless you are providing < 2 parameters. Requires manual editing via VPX "Compile code"
  • Use parenthesis where necessary in complex or ambiguous expressions to indicate the order of operations or logic. Requires manual editing
    • Example: If (mode = 4 Or (mode = 6 And ballDrained = False)) And gameInProgress = True Then AddScore (6 + 3) * bonusX
• Colons / Chained code Separate chained code
  • Do not put multiple calls on the same line; an If/Then condition with a single call is acceptable. General rule of thumb: If you would have needed to use a colon, then it should go on a new line instead.
    • Acceptable: If mode = 2 Then doSomething()
    • Not Acceptable: For i = 0 To 5 : light(i).state = 0 : Next (not easily readable)
    • Not Acceptable: If mode = 2 Then doSomething() : doSomethingElse() (not easily readable and may break code auto-formatters due to a missing "End If" [even though the code would still run fine])
    • Not Acceptable: Dim myVar : myVar = 0 'Comment about myVar (breaks display of comments for the variable in the IDE IntelliSense)
• Comments
  • Commented-out code: After the apostrophe which starts the comment, add a tab before the code. This helps differentiate commented out code from actual comments. Requires manual editing
    • The tab must be added after the apostrophe, not before. Otherwise, "Fix Indentations" will treat it as an unnecessary indentation and undo it.
    • Example: ' Set myVar = new Doggy
  • Section Headers: Requires manual editing
    • Separate section headers with a blank line before it starts and a blank line after it ends.
    • Section headers should use multiple comment lines.
    • The top and bottom line should contain a row of asterisks.
    • Add the header text in between the asterisk lines.
    • Use all-caps section titles for primary / important sections.
    • Use section headers between major script libraries (see examples in the VPW example table), including a header to indicate the end of a library's code with the words "END library name".
    • Section headers indicating the start of a library should include the library's name, authors, version number (use the semantic versioning 2.0 standard), changelog, description / what it does, and implementation instructions.
  • Put a comment on the same line where you declare a method/routine/variable/class/etc to the right of it explaining concisely and briefly what it is and what it does. This ensures the IDE will display the comment whenever you or someone else hovers over its name anywhere in the code. You may put additional documentation in comments directly above it, but they will not show up in the IDE / IntelliSense. Requires manual editing
    • Example: Dim myVar 'Comment for myVar goes here
    • Example: Sub mySub(mark, bob) 'Comment for mySub goes here
  • When a comment refers to a block of code:
    • Put the comment directly above the block of code. Requires manual editing
    • Add a blank line above the comment. Add blank line before comment lines
    • Add another blank line after the end of the code to which the comment refers. Requires manual editing
    • Ensure there are no blank lines between the comment and the end of the block of code which the comment refers. Requires manual editing
    • Example: