Coding Guidelines

From K-3D

Jump to: navigation, search

A few random guidelines on writing new code in K-3D:

  • Prefer to use the C++ Standard Library wherever possible, which means: everywhere.
  • Have a look at this document which provides good advice about dos and dont's to C++ developers. It was written for KDE developers, but the "General C++" section is for everyone!
  • This shouldn't need to be said, but iostreams are part of the Standard Library ... use em! All errors and logging must be written to k3d::log() ... see Logging.
  • Use the K-3D Fundamental Types in all new code.
  • For facilities not provided by the Standard Library, prefer to use the boost library wherever possible.
  • Use k3d::filesystem for all filesystem-related activities, including storage and manipulation of file paths.
  • Use k3d::ustring for storage and manipulation of UTF-8 strings.
  • String arguments to functions should nearly always be of type "const k3d::string_t&".
  • Functions that return strings should nearly always return type "const k3d::string_t".
  • Do not test the result of operator new for a null pointer - operator new throws an exception if an object can't be created.
  • Do not test whether a pointer is null before deleting it - operator delete ignores null pointers - it's part of the C++ Standard.
  • All code in the SDK (k3dsdk library) must go in the "k3d" namespace. Thus, k3d::mesh instead of k3dMesh, k3d::ibitmap instead of k3dIBitmap. There are probably a few symbols out in the world using mixed-case names in the global namespace, but they are deprecated.
  • We use doxygen to create our source-code documentation. Comment your code liberally with doxygen-compatible comments. At a minimum, add a brief description to all classes, functions, and member data by preceding them with a comment that has three slashes:
/// Provides a standardized GUI button component
class button
{
public:
  /// Called by the signal system when the user presses the button
  void on_click();
private:
  /// Stores the current state of the button (pressed / not pressed)
  bool m_pressed;
};
  • You are of course free to provide more thorough documentation using the many features available in doxygen.
  • Changes to the SDK (k3dsdk library) and especially changes to interfaces (those abstract classes defined in k3dsdk whose names begin with "i" ... k3d::iobject, k3d::iproperty, etc.) must be cleared with Tim prior to checkin. Be prepared to defend your design decisions with specificity. That means that you should be prepared to provide the complete public interface for your design, and demonstrate an understanding of the interactions between objects, object lifetimes, performance considerations, and complexity guarantees.
  • Speculative functionality - functionality that you aren't going to put to use right now - is to be particularly avoided. Never expand the public interface to an object unless it is an immediate requirement.
Personal tools