MAME Coding Conventions - Revision history

Cuavas: /* Naming */

2017-07-24T12:06:30Z

Naming

← Older revision		Revision as of 14:06, 24 July 2017
Line 17:		Line 17:
	* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>		* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
	**static constant members should be treated as constants and should be in ALL_CAPS_UNDER_FORMAT (e.g., <code>MAXIMUM_ITEMS</code>)		**static constant members should be treated as constants and should be in ALL_CAPS_UNDER_FORMAT (e.g., <code>MAXIMUM_ITEMS</code>)
			* template parameters should be named using the <code>PascalCaseConvention</code>
	* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>		* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>
	* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)		* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)

Cuavas at 14:14, 7 July 2016

2016-07-07T14:14:12Z

← Older revision		Revision as of 16:14, 7 July 2016
Line 8:		Line 8:

	== Naming ==		== Naming ==
	* function, method, and variable names use the <code>lower_under_convention</code>		* class, function, method, and variable names use the <code>lower_under_convention</code>
	* static member functions may have a static_ prefix (e.g., <code>static_timer_callback</code>)
	* not everyone uses scope prefixes, but if you're going to, please follow this convention:		* not everyone uses scope prefixes, but if you're going to, please follow this convention:
	** instance member variables should have an m_ prefix (e.g., <code>m_device</code>, <code>m_config</code>, etc.)		** instance member variables should have an m_ prefix (e.g., <code>m_device</code>, <code>m_config</code>, etc.)
Line 15:		Line 14:
	** global variables should have a g_ prefix (e.g., <code>g_profiler</code>, etc.)		** global variables should have a g_ prefix (e.g., <code>g_profiler</code>, etc.)
	** file scope variables (file statics or anonymous namespace) should have an f_ prefix (e.g., <code>f_ntfs_offset</code>, etc.)		** file scope variables (file statics or anonymous namespace) should have an f_ prefix (e.g., <code>f_ntfs_offset</code>, etc.)
	** static ~~constant members should be treated as constants and should be in ALL_CAPS_UNDER_FORMAT~~ (e.g., <code>~~MAXIMUM_ITEMS~~</code>)		** static member functions may have a static_ prefix (e.g., <code>static_timer_callback</code>)
	* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>		* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
			**static constant members should be treated as constants and should be in ALL_CAPS_UNDER_FORMAT (e.g., <code>MAXIMUM_ITEMS</code>)
	* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>		* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>
	* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)		* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)
Line 34:		Line 34:
	* no space between parenthesis/bracket and the inner expression: <code>(((i + j) * k) >> m)</code>		* no space between parenthesis/bracket and the inner expression: <code>(((i + j) * k) >> m)</code>
	* use blank lines to visually separate logical blocks; use more consecutive blank lines to separate bigger logical blocks		* use blank lines to visually separate logical blocks; use more consecutive blank lines to separate bigger logical blocks

			== Scoping ==
			* in general, keep scoping as tight as possible — tighter scope makes code easier to analyse
			* keep members private to protected if possible and provide accessors for externally visible state
			* use protected inheritance if the base class/struct isn't part of the interface
			* declare constants inside the public section of classes they're relevant to
			* restrict local variable scope to parts of the function where they're needed needed
			* use anonymous namespaces for things that shouldn't be visible outside a single source file

	== Language conventions ==		== Language conventions ==

Cuavas at 12:52, 7 July 2016

2016-07-07T12:52:23Z

Show changes

Aaron at 18:31, 12 September 2012

2012-09-12T18:31:56Z

← Older revision		Revision as of 20:31, 12 September 2012
Line 101:		Line 101:
	** externally referenced functions		** externally referenced functions
	** internal functions (in same order as prototyped)		** internal functions (in same order as prototyped)

			Back to [[How MAME Works]]

Aaron: /* Naming */

2012-09-12T18:29:06Z

Naming

← Older revision		Revision as of 20:29, 12 September 2012
Line 24:		Line 24:
	** normal variables should have an m_ prefix (e.g., <code>m_device</code>, <code>m_config</code>, etc)		** normal variables should have an m_ prefix (e.g., <code>m_device</code>, <code>m_config</code>, etc)
	** static members should have an s_ prefix (e.g., <code>s_device_table</code>)		** static members should have an s_ prefix (e.g., <code>s_device_table</code>)
	** static constant members should ~~have a k_ prefix~~ (e.g., <code>~~k_maximum_items~~</code>)		** static constant members should be treated as constants and should be in ALL_CAPS_UNDER_FORMAT (e.g., <code>MAXIMUM_ITEMS</code>)
	* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>		* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
	* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>		* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>

Aaron: /* Language conventions */

2010-05-21T19:45:01Z

Language conventions

← Older revision		Revision as of 21:45, 21 May 2010
Line 52:		Line 52:

	== Language conventions ==		== Language conventions ==
			* prefer references over pointers, using pointers primarily in situations where NULL is a valid option
	* use '''static''' and '''const''' keywords aggressively where appropriate		* use '''static''' and '''const''' keywords aggressively where appropriate
	* create typedefs for function pointers; example: <code>typedef void (*my_callback_func)(UINT32 param);</code>		* create typedefs for function pointers; example: <code>typedef void (*my_callback_func)(UINT32 param);</code>

Aaron at 19:41, 21 May 2010

2010-05-21T19:41:25Z

← Older revision		Revision as of 21:41, 21 May 2010
Line 14:		Line 14:
	The first two pieces (the core and OSD) are in general only handled by a small group of developers, while the remaining pieces (drivers and CPU/sound cores) come from a much broader audience. Furthermore, the drivers and CPU/sound cores all interact to some degree with core and OSD pieces below them, so the most benefit from code clarity and consistency comes from making the core and OSD pieces consistent.		The first two pieces (the core and OSD) are in general only handled by a small group of developers, while the remaining pieces (drivers and CPU/sound cores) come from a much broader audience. Furthermore, the drivers and CPU/sound cores all interact to some degree with core and OSD pieces below them, so the most benefit from code clarity and consistency comes from making the core and OSD pieces consistent.

	With that in mind, below is an outline some of the key coding conventions currently in use in the core and OSD layers. If you are modifying code in ~~theses~~ layers and wish to have it accepted upon submission, you would do well to keep to these guidelines. (In fact, if you are modifying any file in any project, you should adopt the conventions of that file/project, rather than just stuffing your own inconsistent style in the middle of something else. I can't believe how many people just ignore the existing styles and jam their own style in the middle.)		With that in mind, below is an outline some of the key coding conventions currently in use in the core and OSD layers. If you are modifying code in these layers and wish to have it accepted upon submission, you would do well to keep to these guidelines. (In fact, if you are modifying any file in any project, you should adopt the conventions of that file/project, rather than just stuffing your own inconsistent style in the middle of something else. I can't believe how many people just ignore the existing styles and jam their own style in the middle.)

	One more thing. Keep in mind that coding conventions are like religion: they are often strongly-held beliefs with little factual justification to back them up. You may disagree with them. Heck, even I disagree with a few of them. But they are the conventions that are used. Deal with it.		One more thing. Keep in mind that coding conventions are like religion: they are often strongly-held beliefs with little factual justification to back them up. You may disagree with them. Heck, even I disagree with a few of them. But they are the conventions that are used. Deal with it.

Aaron: /* Language conventions */

2010-05-21T19:40:37Z

Language conventions

← Older revision		Revision as of 21:40, 21 May 2010
Line 56:		Line 56:
	* make calls through function pointers explicit — example: <code>(*funcptr)(a, b)</code>		* make calls through function pointers explicit — example: <code>(*funcptr)(a, b)</code>
	* wherever possible, use '''enum''' instead of a macro		* wherever possible, use '''enum''' instead of a macro
	* wherever possible, use '''~~INLINE~~''' functions instead of macros		* wherever possible, use '''inline''' functions instead of macros
			* wherever possible, use templates instead of macros
	* macros that look like functions should be wrapped with <code>do { <macrobody> } while (0)</code>		* macros that look like functions should be wrapped with <code>do { <macrobody> } while (0)</code>

Aaron: /* Comments */

2010-05-21T19:39:22Z

Comments

← Older revision		Revision as of 21:39, 21 May 2010
Line 31:		Line 31:

	== Comments ==		== Comments ==
	* comments in ~~the non-OSD parts of~~ the code ~~should all~~ be <code>/* C-style comments */</code>		* comments in the code are preferred to be <code>// C++-style comments</code>, though <code>/* standard C-style comments */</code> are still very common
	* comments in the OSD-specific parts of the code may be <code>// C++-style comments</code> ~~(and~~ are ~~in the Windows code)~~
	* each function should have a comment preceding it that briefly describes what that function does		* each function should have a comment preceding it that briefly describes what that function does
			* each file should begin with a header that includes information about the licensing of that file; if no licensing information is given, the standard MAME license is assumed

	== Spacing ==		== Spacing ==

Aaron: /* Naming */

2010-05-21T19:37:50Z

Naming

← Older revision		Revision as of 21:37, 21 May 2010
Line 20:		Line 20:
	== Naming ==		== Naming ==
	* function, method, and variable names are named using the <code>lower_under_convention</code>		* function, method, and variable names are named using the <code>lower_under_convention</code>
	* static member functions should have a static_ prefix (e.g., static_timer_callback)		* static member functions should have a static_ prefix (e.g., <code>static_timer_callback</code>)
	* member variables within a class should have a standard prefix, as follows:		* member variables within a class should have a standard prefix, as follows:
	** normal variables should have an m_ prefix (e.g., m_device, m_config, etc)		** normal variables should have an m_ prefix (e.g., <code>m_device</code>, <code>m_config</code>, etc)
	** static members should have an s_ prefix (e.g., s_device_table)		** static members should have an s_ prefix (e.g., <code>s_device_table</code>)
	** static constant members should have a k_ prefix (e.g., k_maximum_items)		** static constant members should have a k_ prefix (e.g., <code>k_maximum_items</code>)
	* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>		* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
	* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>		* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>