Development Guidelines

General Principles

MCModeler is written in C++ for reasons of speed (to somewhat make up for my near total ignorance of OpenGL) and to take advantage of the cross-platform Qt library. C++ as a language leaves a lot to be desired, but if sufficient care is taken one can avoid blowing off one's entire foot in most cases.

When writing MCModeler, I have tried my best to write code that encourages modularity, simplicity, and ease of debugging. In particular:

1. Use simple smart pointers (such as QScopedPointer), or use QObject's tree-based memory management. If you find yourself ever typing the word delete, you're probably doing something wrong.
2. Avoid complex smart pointers (such as QSharedPointer) unless you absolutely need to use them. The use of smart pointers like these implies that the ownership of an object is not well-defined, which is sometimes okay, but is often indicative of bad design.
3. Limit the use of templates, and do not use template metaprogramming. The template language in C++ is subtle and can have many unexpected side effects, not to mention producing the most unintelligible error messages imaginable when they go wrong.
4. Take advantage of Qt features like signals, slots, properties, meta-objects, etc. when they make sense, but resist the temptation to make everything a subclass of QObject. Save the power for when you really need it.
5. Write object-oriented code. This means small classes with well-defined responsibilities. Prefer entity classes to "manager" classes. If your class name ends in "-er", consider whether you may actually just be writing procedural code in a colorful object-oriented candy shell.

Style Guide

MCModeler uses the Google C++ style guide with the following exceptions:

The maximum line length is 120 columns, not 80 columns.

Default arguments are allowed. They avoid needless code duplication and make it much easier to add functionality without changing huge numbers of call sites. However, read the section in the Google style guide about them, and only use them when they really make sense. Also remember that constructors with multiple arguments may still need the explicit keyword if all but one of the arguments is a default argument.

Use Doxygen header comments in Javadoc style. Refer to parameters using the \p escape.

// GOOD:
/**
 * Reticulates the splines.
 * @param splines The splines to reticulate.
 * @return True if \p splines could be reticulated.
 */
 bool reticulateSplines();

// BAD:
// Reticulates the splines.
// \param splines The splines to reticulate.
// @return True if |splines| could be reticulated.
bool reticulateSplines();

Use Qt style for method names, not Google style.

// GOOD:
void doSomethingAwesome();

// BAD:
void DoSomethingAwesome();

// GOOD:
int awesomeness();
void setAwesomeness(int awesomeness);

// BAD:
int GetAwesomeness();
int getAwesomeness();
void set_awesomeness(int awesomeness);
void SetAwesomeness(int awesomeness);

Since Google's DISALLOW_COPY_AND_ASSIGN macro does not exist, use Qt's Q_DISABLE_COPY macro instead. It does the same thing.