Coding Conventions

• Class Comments:
  Class comments should start each .vb file. These will be formatted as follows: 

'/**

' The Control Center class is a test class for Doxygen documentation.

'

' @author Brett Peake

' @version 1.0 first documented version

'**/

• Function Comments:
  Function comments should precede every sub/function. These will be formatted as follows: 

'/**

' Some function description text

' @return [As Boolean] is True, while object is pending

'**/

• Option Strict:
  At the beginning of all .vb code files, after the header class comment, "Option Strict" should be turned on. This will cause compile-time errors if type information is omitted at variable declaration (ie: no late binding). By default option strict should turn option explict on (which we also want). 

ex: Option Strict On

• Function Names:
  Functions Names will begin with a capital character and will then use a capital-case character for the start of every word in the variable. The rest of the charcters will be lowercase.

ex: Private Sub SomeFunctionName (ByVal someInput As Intenger)

• Local Variables:
  Variable names will begin with a lower-case character and will then use a capital-case character for the start of every word in the variable. All other charcters will be lowercase (ie: Camal case).

ex: Dim someVariableName As Integer

• Class Variables:
  Class Variable names will begin with the character 'm' and then will use a capital-case character for the start of every word in the variable. All other charcters will be lowercase (ie: Camal case).

ex: Dim mSomeClassVariable As Integer

• Global Variables:
  Global Variable names will begin with the character 'g' and then will use a capital-case character for the start of every word in the variable. All other charcters will be lowercase (ie: Camal case).

ex: Dim gSomeGlobalVariable As Integer

• Constant Variables:
  Constant Variable names will be all uppercase, with the different words seperated by the underscore character. 

 ex: Public const SOME_CONSTANT_NAME As Integer = 7

• GUI Objects:
  For GUI objects, the name will be prefixed by the a 3-letter acronym representing the type of object. The remainder of the name will be in camal-case format.

 ex: txtSomeTextBox 

I would like to suggest we not set a convention for Option Strict, after hours of testing and coding this is more of a pain in the ass than necessary. Since I am using ArrayList types to control motion plans it stores data as 'Object' type, which implies late binding... which as you know means the damn thing won't compile with Option Strict. I tried using direct casts and everything but no go, we will be unable to use Object types if you keep this convention, and personally I don't really want to rewrite all my code to handle jagged arrays of integers and all the functions required to manage them (since arraylist has so many oh-so-useful builtin ones ;) )

We could set the convention to Option Explicit, which will still catch most problems such as data declarations

~ David Fawcett

There are a lot of special tags we can consider adding to the class/function comments for doxygen to pull out. They are listed here: Here is a link . If anyone finds some special tags they feel should be added to our format please bring it up. ~bpeake

Please add any coding conventions you think we should discuss/agree upon to the list ~bpeake