This section contains the latest notable updates made to the style guide.

Latest Documentation Updates

This style provides a common, shared set of (lightweight) guidelines for anyone who wishes to contribute source code and/or scripts to the UOX3 project, in order to help ensure that those contributions follow a standardized approach not only for code style, but also for conventions and practices used in the project. This also improves the maintainability of the project in the future.

The UOX3 code base has historically been a hodgepodge of different styles and approaches, written by people with varying programming skills over a period of more than 20 years, and that history highlights the need for a standard that can be followed when working on the project.

These guidelines are not meant to be understood as hard requirements, yet the closer to the guidelines that new contributions adhere to, the easier it will be to review any changes in context of the current code base and - if accepted - merge those contributions in.

Above all else, please take to heart the general guidelines listed below and follow them as best you can:

• Write understandable, self-documenting code - Give sensible, descriptive names to classes, functions and variables that clarify their purpose, rather than short and ambiguous names that say nothing about what they are for.
• Add comments where needed - Use comments to leave hints for the reader of your code if the code is not self-explanatory for the average programmer. If the code you write is so advanced and complex that no one else can understand it by reading it, then comments are crucial for anyone else to be able to maintain it if/once you've lost interest in the project and moved on (as happens).
• Be consistent with existing code - Make life easy for anyone who needs to read or maintain your code in the future, by adopting the coding style, conventions and practices most commonly used in the project. If the existing code offers two alternatives on how to proceed in this context, choose one of the two; don't introduce a third option.
• Avoid making unnecessary, sweeping style changes - If possible, avoid making sweeping changes throughout the entire code base that forces everyone else to adopt your own preferred style. Not only is it quite an assumption to make that everyone else on the project will prefer your style, it may also cause problems for anyone who wishes to merge their code changes with yours; instead of comparing differences in a few functions in a few files, they now potentially have thousands of differences to go through!
• If unsure, ask - If you're unsure if a change would conflict with the guidelines laid out in this Style Guide, don't hesitate to bring it up in Discord or on the UOX3 Community forums to get a second opinion - preferably before you make the change!

If you have identified a need for a change that conflicts with the above points, or with anything else in this Style Guide, create a new topic on the Communtiy Forums and state your case, or bring it up in the Discord chat. None of these "rules" are etched in stone, they can (and should) be challenged, updated and added to when appropriate.

Currently, any new code written for UOX3 should target C++11 to C++17, and aim to be cross-platform conforming across Windows, Linux and macOS platforms, when compiled using VS2017-2022, GCC/G++ v8-9 and/or CMake v?. Avoid using features specific to C++20 or newer, to not introduce additional compiler dependencies and requirements.

• C++17 Cheatsheet
• C++14 Cheatsheet
• C++11 Cheatsheet

UOX3 aims to be cross-platform conformant across (at least) 64-bit Windows, Linux and macOS platforms, with feature parity between each platform. Implementations specific to any one particular platform should be avoided if possible, though there might be exceptions for special cases where platform-specific handling is unavoidable - such as when dealing with console and/or networking.

Any code being contributed that does not compile, run and function the same on all the above-mentioned platforms will probably not be approved for inclusion in UOX3 until/unless necessary changes have been made to comply with the above.

Use Self-Descriptive Names

Always prefer self-descriptive names (skillUsageDelay instead of skUseDel, itemCount instead of ic)

Filenames

If creation of new source files is necessary, use camelCase when naming the files to make the name more readable in a list of other, perhaps similarly named files. Try to stick close to existing naming practice.

Classes/Methods/Functions

Use PascalCase for class/function/method names.

Variables and Parameters

Use camelCase for variables, non-method class/struct members and function/method parameters.

Function/Method Comment Blocks

This Style Guide makes no differentiation between functions and methods for the purpose of comment blocks.

• Comment blocks should be added for any new functions or methods added, should describe the purpose of the function/method and provide any extra context that is relevant for future maintainers of the code. For the sake of making the maintenance of comments more manageable, adopt a minimalistic approach where only relevant details are included:

//o-----------------------------------------------------------------------------------------------o
//| Function	-	CSocket::AddTrigWord()
//o-----------------------------------------------------------------------------------------------o
//| Purpose		-	Adds trigger word to list of trigger words detected in player's speech
//o-----------------------------------------------------------------------------------------------o

• Getters/setters that have been grouped together should be commented together, where possible:

//o-----------------------------------------------------------------------------------------------o
//| Function	-	CSocket::TargetOK()
//o-----------------------------------------------------------------------------------------------o
//| Purpose		-	Gets/Sets socket property to indicate whether waiting for client target
//o-----------------------------------------------------------------------------------------------o
auto CSocket::TargetOK( void ) const -> bool
{
	return targetok;
}
auto CSocket::TargetOK( bool newValue ) -> void
{
	targetok = newValue;
}

General Comments

• Pay attention to grammar, spelling and punctuation, even in comments
• Variables in general should have names that are descriptive enough that they'd not need comments, but if comments are needed - add them!
• For global variables, try to always add a comment to explain what it's used for, and potentially why it needs to be a global variable
• Don't remove comments added by other maintainers unless the comments in question are no longer relevant/accurate
• If the use of magic numbers is necessary, add context for the magic number via comments
• When deciding what to comment or not, try to think from the perspective of people maintaining the code after you're gone. Is it likely that someone will need some extra context to understand your code? Add a comment.

• Make liberal use of const. Any member function that does not modify its object should be const. Any function parameter that references an object, but doesn't actually change it, should be passed as a const reference.
• For function parameters passed by value, const has no effect on the caller, and is not needed
• When declaring something as const, follow this pattern: const int *foo (const comes first)

Write Short Functions

• Write short functions, whenever possible. Sometimes it makes sense for a function to be a bit longer, but if the code in a function exceeds ~40 lines, start thinking about whether it could be broken up.
• Short functions are easier to read, easier to test, easier to debug, and easier to modify.

• Group getters and setters for class members together in pairs; put the getter for X next to the setter for X. Avoid spreading them out to different sections of a file. Grouping them up makes the code easier to read, maintain and debug:

auto CItem::GetType( void ) const -> ItemTypes
{
	return type;
}
auto CItem::SetType( ItemTypes newValue ) -> void
{
	type = newValue;
}

• Declare local variables when you need to use them, and not a moment sooner. The narrower the scope for a variable, and the closer it is declared to where it is actually used, the easier it becomes to read and understand the code for future code maintainers (or yourself a month from now).
• If possible initialize variables as they are declared, instead of declaring and then assigning values to them separately, so whoever reads the code can see at a glance both the type and value the variable was initialized to.

Example:

// Not ideal
std::string myString;
myString = "Hello";

// Better
std::string myString = "Hello";

// Preferred
auto myString = "Hello"s; // note the 's' at the end

• Exception: If the variable is an object, and it's used in a for-loop, declare it outside the for-loop so the constructor and destructor of the object doesn't get invoked multiple times as it loops.

• Use the auto keyword when declaring variables to automatically deduct the variable type based on the initializer. Same can be done with return types for functions. Examples:

// Using auto with a variable
auto myChar = "Hello"; // type is const char* pointer to const char[5] array
auto myString = "Hello, World!"s; // type is std::string (note the 's' at the end)
auto myVar = GetMyVarValue(); // type depends on what GetMyVarValue() returns

// Using auto with functions
auto CItem::SetRegion( UI16 newValue ) -> void
{
	regionNum = newValue;
	UpdateRegion();
}
auto CItem::GetRegionNum( void ) const -> UI16
{
	return regionNum;
}

• Use the UOX3-defined type aliases like UI16, SI32, etc. for different integer types where possible, to increase readability and maintainability of the code. These are defined as follows:

  using R32 = float;
  using R64 = double;
  using UI08 = std::uint8_t;	// 0 to 255
  using SI08 = std::int8_t;	// -128 to 127
  using UI16 = std::uint16_t;	// 0 to 65535
  using SI16 = std::int16_t;	// -32768 to 32767
  using UI32 = std::uint32_t;	// 0 to 4294967295
  using SI32 = std::int32_t;	// -2147483648 to 2147483647
  using UI64 = std::uint64_t;	// 0 to 18446744073709551615
  using SI64 = std::int64_t;	// -9223372036854775808 to 9223372036854775807

• Use C++-style casts, and avoid C-style casts. Example:

  // Good - C++-style cast
  static_cast<R32>( double_value )
  
  // Avoid - C-style cast
  ( R32 )double_value

• When in doubt about how large integer type is needed, prefer the larger type unless(i.e. UI64 over UI32, or SI32 over SI16)

Tabs vs Spaces

For consistency with the rest of the code base, indent your code using tabs (size: 4), not spaces.

Indentation

• Vertical alignment can be done to increase readability in certain situations, like:

case CCP_FAME:			*vp = INT_TO_JSVAL( gPriv->GetFame() );					break;
case CCP_KARMA:			*vp = INT_TO_JSVAL( gPriv->GetKarma() );				break;
case CCP_ATTACK:		*vp = INT_TO_JSVAL( Combat->calcAtt( gPriv, true ));	break;
case CCP_CANATTACK:		*vp = BOOLEAN_TO_JSVAL( gPriv->GetCanAttack() );		break;
case CCP_BRKPEACE:		*vp = INT_TO_JSVAL( gPriv->GetBrkPeaceChance() );		break;
case CCP_HUNGER:		*vp = INT_TO_JSVAL( gPriv->GetHunger() );				break;

pStream.ReserveSize( 44 );
pStream.WriteByte(   0, 0x1C );
pStream.WriteShort(  1, 44 );
pStream.WriteLong(   3, 0xFFFFFFFF );
pStream.WriteShort(  7, 0xFFFF );
pStream.WriteString( 14, "System", 6 );
pStream.WriteByte(   20, 0 );

Whitespace Guidelines

• Spaces inside parentheses

( x, y, z )

• Spaces after commas in list/function/method parameters

void MyFunction( std::string myString, int myInt )

• Spaces around operators

var foo = x - 1;
var bar = x <= 10;

• No spaces before parentheses in function or method declarations

bool myClass::MyMethod()

• No spaces before parentheses in control statements

if( x == 1 )
for( int i = 0; i < 10; ++i )

• No spaces between multiple parentheses in control statements

if( foo || ( !bar ))
if(( x == y ) && ( z != x ))

• No spaces inside angled or square brackets, except after comma, or between operators

[x, y, z]
static_cast<SI16>

Braces

• Braces ALWAYS on their own lines (Allman style)

if( something )
{
  ...
}

void myFunction( std::string myString )
{
}

• Always use braces with if & else statements, even for one liners, to prevent easy mistakes by future maintainers

if( something )
{
	// one liner
}

• Exception to the previous point: Braces can be skipped for one-liners that are intended to return early, continue/break a loop, etc. In those cases, try to leave an empty line after the early return/continue/break and the rest of the code in the function/method in question

bool cScript::OnCreate( CBaseObject *thingCreated, bool dfnCreated )
{
	if( !ValidateObject( thingCreated ))
		return false;

	std::string functionName = "onCreateDFN";
	...
}

for( auto &MapArea : MapRegion->PopulateList( this ))
{
	if( MapArea == nullptr )
		continue;

	// First remove nearby characters from sight
	...
}