Our coding standards

Philip asked via the Suggestion Box about what sort of coding standards and design philosophies do we use at REAL Software when working on REALbasic, so I figured I'd discuss that a little bit. We don't do anything too terribly radical, so much of this won't come as a surprise to you.

We use two different languages to do our work: REALbasic is used when working on the IDE and parts of the framework, and C++ is used when working on the compiler and parts of the framework. So, without further ado, here's the coding standards we have (pulled straight from our "handbook.")

General

• All control statements have a space after the control keyword and before the open paren (if a paren is needed)

          // Correct
          if (true) {
          }
             
          // Incorrect
          if(true) {
          }
  

• All expressions should use spaces between parts

          // Correct
          if (i == 12 and cool == true) {
          }
             
          // Incorrect
          if (i==12&&cool==true) {
          }
  

• All class and method names are titlecased

          // Correct
          class Win32SerialControl
             
          // Incorrect
          class Win32_Serial_Control
          class Win32serialcontrol  
  

• All class properties are titlecased and prefixed with "m"
• All constants are titlecased and prefixed with "k"
• You should use globals sparingly, but if you use them, they should be in globals.cpp/h, and be prefixed with "g"
• If you create a static variable, it should be prefixed with "s"

          // Correct
          int mTesting;
          const int kTesting = 12;
          extern int gSomeGlobal;
          bool sSomeStatic = true;
  
          // Incorrect
  
          int testing;
  
          int Testing;
  
          int m_Testing;
  
          const int Testing = 12;
  
          const int k_Testing = 12;
  
  



• All local variables and method parameters are titlecased, except for the first letter


• All parameter lists have a space after the open paren, and before the close paren
  

  
  
          // Correct
  
          int Foo( int localVariableOne, string localVariableTwo );
  
             
  
          // Incorrect
  
          int Foo(int local_variable, string HaHaHa);
  
          int foo(int local_variable, string HaHaHa);
  
  



• All classes and class members are as closely encapsulated as possible by making them protected or private, based on need.


• Make use of the assert macro/function call to test your assumptions about code invariants. If something should always be true, then assert it! If your assertion fails, then you should expect that the application will terminate. To this end, you should not be using assertions to validate user input (or the likes). If you wish to make a recoverable assertion (in the IDE only), then you should use the AssertOrRecover function instead of Assert.


• You should never have any "magic numbers" in your code. You should always use a descriptive constant instead
  

  
  
          // Correct
  
          ctl.Left = ctl.Left + kMargin
  
  
          // Incorrect
  
          ctl.Left = ctl.Left + 2
  
  



• If you have incomplete code that needs to be addressed in the future, you should put in a ToDo comment that explains what needs to happen, and wrap it in a #if RBVersion block as to when the code should be addressed.
  

  
  
          // ToDo: This code needs to be updated because
  
          // gremlins live in it here and here, and since
  
          // it is 2008r1, we want to address this in the
  
          // next release.
  
          #if RBVersion > 2008.01
  
            Bad code
  
          #endif
  
  



• You should never introduce new warnings. When you're working on some source code, you should always try to remove warnings that you come across. The goal is to have no warnings, ever.

C++ Specific

• All macros are all uppercased

          #define    MIN( a, b )    ((a

• Always use curly braces for multiline control statements
• Openining curly braces are at the end of the line, not the beginning, closing curly braces line up with scope opener

          // Correct
          if (true) {
              printf( "true" );
          }
             
          // Also correct
          if (true)    printf( "true" );
             
          // Incorrect
          if (true)
              printf( "true" );
             
          // Incorrect
          if (true)
          {
              printf( "true" );
          }
  

• All methods should have a comment header that describes the method, its parameter list, and its return value

          // IsDataAvailable
          //
          //    Checks to see whether there is new data available for
          //    the serial device to read
          //
          // Author: AJB
          // Used In: runtime
          // Gets: the serial control
          // Returns: true if there's data waiting to be read
          // Comment: Feb 17 2006 -- AJB (1)
          static Boolean IsDataAvailable( SerialControl *ctl )
          {
              ...
          }
  

RB Specific

• The only Global items allowed are classes
• Do not make Public simple properties -- use computed properties instead
• If a method raises an exception, explicitly document it at the top of the method
• If an API you're calling can raise an exception, enclose it in a try/catch block with an explicit exception filter

          // Correct
          try
              foo = someDict.Value( 12 )
          catch err as KeyNotFoundException
          end try
             
          // Incorrect
          try
              foo = someDict.Value( 12 )
          catch
          end try
             
          // Incorrect
          foo = someDict.Value( 12 )
          ..
          ..
          exception err as KeyNotFoundException
  

• All method calls should use parens for the parameter list, even when their use is optional
  

  
  
          // Correct
  
          MsgBox( "Hello world" )
  
             
  
          // Incorrect
  
          MsgBox "Hellow world"
  
  




• All permanent comments should be using // instead of ' or REM
  

  
  
          // Correct
  
          // See how pretty my code is?
  
             
  
          ' Incorrect
  
          ' See how ugly my comments are?
  
  




• All temporary comments should be using ' instead of // or REM
  

  
  
          // Correct
  
          ' Dim i as Integer = 12
  
             
  
          // Incorrect
  
          // Dim i as Integer = 12
  
  



• You should never use a hard-coded string in the IDE for any text that is displayed to the user. You should always use a dynamic string constant (generally in the Strings module)
  

  
  
          // Correct
  
          MsgBox Strings.kHelloWorld
  
  
          // Incorrect
  
          MsgBox "Hello world"
  
  

Now, Philip also asked about design philosophies such as when to improve speed over readability, etc. That's actually a much less formal topic that doesn't have any hard and fast rules. However, it's also pretty easy to explain: write the code to be correct, readable, and maintainable. If speed becomes an issue, then optimize for speed. Very rarely is speed a consideration in the first writing of code, with the exception of the compiler. The compiler requires more of an eye towards speed because it's very, very easy to make a small change with a large speed or memory impact.