Guidelines

Some rules to keep in mind while writing code:

• C bindings should not use long, as that type varies in size between 32 and 64 bits. Instead use c_long.
• int should not be used for array indexes or lengths. Use word instead.
• Use ++ as a prefix operator unless the postfix behavior is desired. That is, the postfix form is fine to use, but only in an expression that uses its value before being incremented.
• Verify all arguments to methods. Errors can be caught closer to where they are made and better error messages can be given. Unless speed is of particular concern, do not use assert for validating arguments, as the checks will be removed in release mode.
• Private variables start with an underscore. This naming convention allows naming properties and method parameters the same but without the underscore.
• Use exceptions for error handling. Follow these guidelines: http://blogs.msdn.com/b/kcwalina/archive/2005/03/16/396787.aspx

Code Style

• Use tabs to indent, as then anyone can change their indentation amount. Tabs are only used for indentation. To line up parameters or equal signs or whatever, use spaces:

    void method() {
    →   foobar(aReallyLongArgumentName,
    →   ·······theSecondArgument);
    }
  

• Usually wrap lines to 100 characters.

• For an infinite loop, never use for(;;). Why should it even compile? There's no condition in it. Why should the default condition be true instead of false? Use while(true) because it actually makes sense.

• Opening braces go on the same line as the preceding class, method, or statement.

Documentation

• Everything that is stable should have documentation, documentation that is not simply rewording what the method's name is. There are often more questions that need answered. What does the method do in certain situations? How does it handle invalid input? How fast is it? What are some example usages? Examples:

  • If an Image class has a property called stride, don't just say "Gets the stride of this image." A better description would be "Gets the number of bytes from one row in this image to the next," as it explains what stride is, in case the reader has not heard of it before.
  • If a method returns the directory that app settings should be stored on the current platform, provide an example path for a couple platforms so that the user can see that it is the right method to use.
  • If an Image class has a property that returns an array of pixel data, tell whether that data is a copy or not. If they aren't both immutable, you'd need to know if one will change when you write to the other. Even ignoring that issue, performance is important and often not an implementation detail. The performance of a method often dictates when it is appropriate to use.

• All properties should have the default documented. So many times in other libraries, there are multiple properties that I need to be a certain value. However, I don't know if I need to set them or if the defaults are good, since I don't know what the defaults are. It would be silly to go through and set every property of every object I create. The only solution is to run the program and see if the default is what I need. It is ridiculous. Documentation fail.

  An example in Qt with a parameter (not even a property) is the OpenMode passed to QIODevice.open(): does using WriteOnly append or truncate? Both of them are flags that can be added. For years, the documentation did not say, but a sentence was recently added with Qt 5.3.

• Spell check documentation.

• Document what every method can throw. .NET documentation is good at documenting exceptions that can be thrown. Reliable programs rely on no exception being thrown that they did not expect. The programmer needs to look through all exceptions that can be thrown and handle them by either preventing the situation that causes them to be thrown or handling them after they are.

• Provide reasoning for why things are named the way they are.

• Documentation for a method should include key words to help people find the method when searching. What people search for is likely what the method was called in another GUI library they used. Therefore, the equivalent method in other GUI libraries should be mentioned. For example, for a repaintLater() method, the words "invalidate" (Windows API and Android) and "update" (Qt) should be mentioned. I could go further and just have a list of the equivalent methods in other libraries.