DarkRadiant coding standards - Revision history

Orbweaver: Additional shared ptr typedef option

2020-08-26T08:31:35Z

Additional shared ptr typedef option

@@ Line 48: / Line 48: @@
 A shared ptr should be named like this (Ptr suffix):
   typedef std::shared_ptr<MyClass> MyClassPtr;
 ===Static variables===

Orbweaver: Add note about not using Boost

2020-08-26T08:26:49Z

Add note about not using Boost

← Older revision		Revision as of 08:26, 26 August 2020
Line 39:		Line 39:
	===Data types and objects===		===Data types and objects===

	* Always use STL or ~~Boost~~ objects, rather than home-grown reinventions of the same thing. Use '''std::string''' for string variables, and '''std::map''' in favour of '''HashedCache'''. Classes that use these home-grown versions should be modified so as not to use them if at all possible, and eventually they will be removed.		* Always use STL or other library objects (e.g. wxWidgets), rather than home-grown reinventions of the same thing. Use '''std::string''' for string variables, and '''std::map''' in favour of '''HashedCache'''. Classes that use these home-grown versions should be modified so as not to use them if at all possible, and eventually they will be removed.
			* Note that ''we are no longer using Boost'', since modern C++ provides almost all of the Boost facilities we previously needed (shared pointers, std::function etc), and avoiding Boost greatly simplifies the Windows build. If you are developing on a platform where Boost is easily available, be careful not to accidentally add a new Boost usage which will break Windows compilation.
	* Do not use '''const char*''' objects except where necessary to pass to a library function (such as the C-based GTK library), or where a string constant is needed. Functions that accept or return strings should use '''std::string''' instead.		* Do not use '''const char*''' objects except where necessary to pass to a library function (such as the C-based GTK library), or where a string constant is needed. Functions that accept or return strings should use '''std::string''' instead.

Orbweaver: Update certain guidelines, add section on indentation

2020-08-26T08:22:54Z

Update certain guidelines, add section on indentation

← Older revision		Revision as of 08:22, 26 August 2020
Line 1:		Line 1:
	Although DarkRadiant was forked from GTKRadiant, the style of legacy GTKRadiant code should ''not'' be used as an example for new code. Therefore these '''coding standards''' should be used for new code, in order to maximise readability for developers.		Although DarkRadiant was forked from GTKRadiant, the style of legacy GTKRadiant code should ''not'' be used as an example for new code. Therefore these '''coding standards''' should be used for new code, in order to maximise readability for developers.

			==Indentation==

			* Prefer 4-space indentation in new code. However, when editing legacy code which is using a different indentation style, it is acceptable to maintain consistency with the legacy code rather than reformatting. Try to avoid mixing tabs and spaces within the same file as this can break alignment when viewing diffs.
			* Function and method bodies should use either the [https://en.wikipedia.org/wiki/Indentation_style#Allman_style Allman] or [https://en.wikipedia.org/wiki/Indentation_style#K&R_styleK&R K&R] brace styles, and where possible the opening brace should be in column 0. This enables developers using Vim to make use of the "[[" shortcut to jump to the beginning of the method.

	==Naming conventions==		==Naming conventions==
Line 6:		Line 11:
	* Class names should begin with a capital letter and capitalise each word: '''RenderablePicoModel''', '''TextMenuItem'''		* Class names should begin with a capital letter and capitalise each word: '''RenderablePicoModel''', '''TextMenuItem'''
	* Classes represent "things", therefore they should be named after nouns not verbs: '''ModuleLoader''' rather than '''LoadModule'''.		* Classes represent "things", therefore they should be named after nouns not verbs: '''ModuleLoader''' rather than '''LoadModule'''.
	* Each ~~new~~ class should be ~~contained within its own~~ file pair: '''MyClass''' is contained in '''MyClass.h''' and '''MyClass.cpp'''. ~~This rule does not apply to tightly-bound local~~ classes~~, such as a functor class which is~~ used ~~by only~~ a single ~~method in a~~ .cpp file. It is also acceptable to define trivial data structures returned by methods in the header file declaring the method, if that data structure is not used elsewhere.		* Each class should be in a file pair with file names matching the class name: '''MyClass''' is contained in '''MyClass.h''' and '''MyClass.cpp'''. Local classes used in a single .cpp file may be defined within that .cpp file. It is also acceptable to define trivial data structures returned by methods in the header file declaring the method, if that data structure is not used elsewhere.
	* Method names and local variables should start with a ~~small~~ letter.		* Method names and local variables should start with a lowercase letter, with subsequent words using camelcase: '''start()''', '''getDataStructure()'''. With wxWidgets, however, the convention is different — methods begin with capital letters just like class names. When writing code that is tightly bound to wxWidgets, it is acceptable to use this same style for methods (but please be consistent).
	* Member variables should begin with an underscore: '''_widget'''. Do not use the "m_name" convention in new code, as this is harder to read.		* Member variables should begin with an underscore: '''_widget'''. Do not use the "m_name" convention in new code, as this is harder to read.

Line 25:		Line 30:
	is a bad typedef. It provides no improved readability over simply using the primitive type, and gives the impression to a reader unfamiliar with the code that a more complex data structure is being used.		is a bad typedef. It provides no improved readability over simply using the primitive type, and gives the impression to a reader unfamiliar with the code that a more complex data structure is being used.

	* Always name typedefs based on what the type is, not what it is for. Use "StringList" rather than "ShaderParameterList" or "ArgumentList".
	* Never use typedefs to rename a standard type (unless there is a specific purpose, like providing a standard public typedef as part of a functor interface).		* Never use typedefs to rename a standard type (unless there is a specific purpose, like providing a standard public typedef as part of a functor interface).

Line 31:		Line 35:

	* Always use Object-Oriented design methods wherever possible. Think in terms of objects which define methods to act on those objects, rather than C-style functions that process data structures passed as arguments. Non-member functions are OK for minor tasks, as long as they are within a namespace rather than at global scope.		* Always use Object-Oriented design methods wherever possible. Think in terms of objects which define methods to act on those objects, rather than C-style functions that process data structures passed as arguments. Non-member functions are OK for minor tasks, as long as they are within a namespace rather than at global scope.
	* Never use global variables.		* Never use global variables (non-constants at file or global scope). Constants at file scope are acceptable, either as primitive types or composite data structures (e.g. vectors or maps) whose content never needs to change.

	===Data types and objects===		===Data types and objects===

Greebo: /* Data allocation */

2014-12-29T03:48:18Z

Data allocation

← Older revision		Revision as of 03:48, 29 December 2014
Line 39:		Line 39:

	=== Data allocation ===		=== Data allocation ===
	Use '''~~boost~~::shared_ptr'''s wherever you need to allocate objects on the heap, as these objects auto-destruct when the last ptr instance is destroyed. Use '''new''' only if you need tight control of when the object should be removed from the heap, or to instantiate GUI classes that auto-destruct in their callbacks.		Use '''std::shared_ptr'''s (or '''std::unqiue_ptr''') wherever you need to allocate objects on the heap, as these objects auto-destruct when the last ptr instance is destroyed. Use '''new''' only if you need tight control of when the object should be removed from the heap, or to instantiate GUI classes that auto-destruct in their callbacks.

	A shared ptr should be named like this (Ptr suffix):		A shared ptr should be named like this (Ptr suffix):
	typedef ~~boost~~::shared_ptr<MyClass> MyClassPtr;		typedef std::shared_ptr<MyClass> MyClassPtr;

	===Static variables===		===Static variables===

Tels: sort under C

2007-11-18T12:10:37Z

sort under C

← Older revision		Revision as of 12:10, 18 November 2007
Line 62:		Line 62:
	Exactly where and how to place comments is a matter of personal preference. However, at the very least, ''all'' public methods and functions should be commented in their associated header file, with details of their parameters, return value and function, along with any other important information (such as prerequisites for calling the function, who is responsible for destroying returned data etc.).		Exactly where and how to place comments is a matter of personal preference. However, at the very least, ''all'' public methods and functions should be commented in their associated header file, with details of their parameters, return value and function, along with any other important information (such as prerequisites for calling the function, who is responsible for destroying returned data etc.).

	{{darkradiant-internal}}		{{darkradiant-internal\|sort=Coding}}

Tels: categorize

2007-11-11T23:22:57Z

categorize

← Older revision		Revision as of 23:22, 11 November 2007
Line 62:		Line 62:
	Exactly where and how to place comments is a matter of personal preference. However, at the very least, ''all'' public methods and functions should be commented in their associated header file, with details of their parameters, return value and function, along with any other important information (such as prerequisites for calling the function, who is responsible for destroying returned data etc.).		Exactly where and how to place comments is a matter of personal preference. However, at the very least, ''all'' public methods and functions should be commented in their associated header file, with details of their parameters, return value and function, along with any other important information (such as prerequisites for calling the function, who is responsible for destroying returned data etc.).

	~~[[Category:DarkRadiant]]~~		{{darkradiant-internal}}
	~~[[Category:Coding]]~~

Greebo: added boost::shared_ptr

2007-04-30T09:26:27Z

added boost::shared_ptr

← Older revision		Revision as of 09:26, 30 April 2007
Line 35:		Line 35:
	===Data types and objects===		===Data types and objects===

	* Always use STL or Boost objects, rather than home-grown reinventions of the same thing. Use '''std::string''', and '''std::map''' in favour of '''HashedCache'''. Classes that use these home-grown versions should be modified so as not to use them if at all possible, and eventually they will be removed.		* Always use STL or Boost objects, rather than home-grown reinventions of the same thing. Use '''std::string''' for string variables, and '''std::map''' in favour of '''HashedCache'''. Classes that use these home-grown versions should be modified so as not to use them if at all possible, and eventually they will be removed.
	* Do not use '''const char*''' objects except where necessary to pass to a library function (such as the C-based GTK library), or where a string constant is needed. Functions that accept or return strings should use '''std::string''' instead.		* Do not use '''const char*''' objects except where necessary to pass to a library function (such as the C-based GTK library), or where a string constant is needed. Functions that accept or return strings should use '''std::string''' instead.

			=== Data allocation ===
			Use '''boost::shared_ptr'''s wherever you need to allocate objects on the heap, as these objects auto-destruct when the last ptr instance is destroyed. Use '''new''' only if you need tight control of when the object should be removed from the heap, or to instantiate GUI classes that auto-destruct in their callbacks.

			A shared ptr should be named like this (Ptr suffix):
			typedef boost::shared_ptr<MyClass> MyClassPtr;

	===Static variables===		===Static variables===

Greebo at 09:22, 30 April 2007

2007-04-30T09:22:44Z

← Older revision		Revision as of 09:22, 30 April 2007
Line 35:		Line 35:
	===Data types and objects===		===Data types and objects===

	* Always use STL or Boost objects, rather than home-grown reinventions of the same thing. Use '''std::string~~''' not '''CopiedString~~''', and '''std::map''' in favour of '''HashedCache'''. Classes that use these home-grown versions should be modified so as not to use them if at all possible, and eventually they will be removed.		* Always use STL or Boost objects, rather than home-grown reinventions of the same thing. Use '''std::string''', and '''std::map''' in favour of '''HashedCache'''. Classes that use these home-grown versions should be modified so as not to use them if at all possible, and eventually they will be removed.
	* Do not use '''const char*''' objects except where necessary to pass to a library function (such as the C-based GTK library), or where a string constant is needed. Functions that accept or return strings should use '''std::string''' instead.		* Do not use '''const char*''' objects except where necessary to pass to a library function (such as the C-based GTK library), or where a string constant is needed. Functions that accept or return strings should use '''std::string''' instead.

Greebo: categorised

2007-01-12T11:43:16Z

categorised

← Older revision		Revision as of 11:43, 12 January 2007
Line 55:		Line 55:

	Exactly where and how to place comments is a matter of personal preference. However, at the very least, ''all'' public methods and functions should be commented in their associated header file, with details of their parameters, return value and function, along with any other important information (such as prerequisites for calling the function, who is responsible for destroying returned data etc.).		Exactly where and how to place comments is a matter of personal preference. However, at the very least, ''all'' public methods and functions should be commented in their associated header file, with details of their parameters, return value and function, along with any other important information (such as prerequisites for calling the function, who is responsible for destroying returned data etc.).

			[[Category:DarkRadiant]]
			[[Category:Coding]]

OrbWeaver: /* Naming conventions */

2006-12-31T18:00:10Z

Naming conventions

@@ Line 9: / Line 9: @@
 * Method names and local variables should start with a small letter.
 * Member variables should begin with an underscore: '''_widget'''. Do not use the "m_name" convention in new code, as this is harder to read.
 ==General code structure==