Style Guide

Style Guide

This document captures the code style preferred for programming in the languages used by the project. Following these guidelines is mandatory and pull requests may be denied for failing to meet these guidelines. Standardizing code style is necessary for maintaining high-quality code and a consistent interface and programming experience across all project components.

C++

Comments

See Doxygen Comment Blocks
See Doxygen Commands

• Avoid spanning comments
• Avoid comment visibility enhancements
• Avoid JavaDoc documentation style
• Prefer Doxygen commands for semantic documentation
• Prefer regular line comments for explanations (e.g. // Find hidden creatures... )
• Prefer triple line comments for documentation (e.g. /// Abstract interface for asset framework)

Good

/// \brief Asset serialization interface
///
/// Provides an interface for querying serialization capabilities
/// for an asset and performing serialization / deserialization.

struct AssetSerializer {
  
  /// Serializes the asset contained by the asset handle.
  ///
  /// \param handle asset handle with asset to serialize
  /// \return true if successful; false otherwise
  
  bool
  serialize(AssetHandle & handle);
  
}

Bad

/***************************************
 * Asset serialization interface       *
 ***************************************/
 
struct AssetSerializer {

    /** 
     * Serializes the asset contained by the asset handle.
     *
     * @param handle asset handle with asset to serialize
     * @return true if successful; false otherwise
     */

    bool 
    serialize(AssetHandle & handle);

}

Scoping

Namespaces

• Avoid using namespace directives
• Avoid inline namespaces

Good

  namespace rpgtoolkit {
      System::System() {
          // Implementation
      }
  }

Bad

  using namespace rpgtoolkit;
  System::System() {
      // Implementation
  }

Naming Conventions

Element	Convention	Example
Namespace	Lowercase Underscored	rpgtoolkit::assets
Type	Pascal	struct AssetHandler { }
Type Member	Lowercase Underscored Suffixed	name_
Type Methods	Pascal	GetWindow()

Namespaces

• Lowercase with underscore separating words
• Prefer monolithic namespaces over nested namespaces
• Prefer common abbreviations
• Prefer single nouns
• Prefer multiple nouns to nested namespaces

Good

rpgtoolkit
rpgtoolkit::io
rpgtoolkit::assets

Bad

RPGToolkit
rpgtoolkit::Assets
RPGTOOLKIT::GRAPHICS
rpgtoolkit::net::http::client

Type Names

• Pascal casing
• Prefer singular nouns and pronouns
• Prefer suffixing base class names

Good

AssetHandle
AssetSerializer
FileAssetHandle
Key

Bad

assetHandle
asset_handle
Asset_Handle
Keys

Type Methods

• Pascal casing
• Prefer verbs and adverbs
• Prefer Get/Set prefix for properties and accessors
• Prefer Is/Can/Has prefix for boolean methods

Good

Window& GetWindow()
void SetHealth(int value)
bool IsAlive()
bool CanRender()
Vector2 CalculateEnemyPosition()

Bad

Window& window()
void set_health(int value)
bool Alive()
bool is_renderable()
Vector2 calculateEnemyPosition()

Type Members

• Lowercase with underscore separating words
• Underscore suffix
• Prefer singular nouns
• Prefer plural nouns for collection-backed members

Good

int health_
string description_
vector<Player> players_

Bad

int m_health
string DESCRIPTION
vector<Player> PlayerCollectionValues

Formatting

Type Definitions

Language Features