PCSX2 Documentation/Code Formatting Guidelines: Difference between revisions

PCSX2 Documentation/Code Formatting Guidelines (view source)

Revision as of 22:26, 8 January 2015

212 bytes added , 8 January 2015

no edit summary

Krysto

ninja

782

edits

@@ Line 18: / Line 18: @@
 Most of the time you want to use either PCSX2 or wxWidgets cross-platform types in the place of C++ atomic types. Most of the common types are:
-```C++
-u8, s8, u16, s16, u32, s32, u64, s64, u128, s128, uptr, sptr
+ <code>u8, s8, u16, s16, u32, s32, u64, s64, u128, s128, uptr, sptr</code>
-```
-These types ensure consistent operand sizes on all compilers and platforms, and should be used almost always when dealing with integer values. There are exceptions where the plain int type may be more ideal, however: typically C++ compilers define an `int` as a value at least 32 bits in length (upper range is compiler/platform specific), and temporary arithmetic operations often conform to this spec and thus can use `int` (a compiler may be allowed then to use whichever data type the target CPU is most efficient at handling). Other C++ integer types such as `short` and `long` should not be used for anything except explicit matching against externally defined 3rc party library functions. They are too unpredictable and have no upside over strict operand sizing.
-Note that using the C++ atomic types `float` and `double` are acceptable, and that there are no defined alternatives at this time.
+These types ensure consistent operand sizes on all compilers and platforms, and should be used almost always when dealing with integer values. There are exceptions where the plain int type may be more ideal, however: typically C++ compilers define an <code>int</code> as a value at least 32 bits in length (upper range is compiler/platform specific), and temporary arithmetic operations often conform to this spec and thus can use <code>int</code> (a compiler may be allowed then to use whichever data type the target CPU is most efficient at handling). Other C++ integer types such as <code>short</code> and <code>long</code> should not be used for anything except explicit matching against externally defined 3rc party library functions. They are too unpredictable and have no upside over strict operand sizing.
-**Special note:** PCSX2-specific types `uptr` and `sptr` are meant to be integer-typed containers for pointer addresses, and should be used in situations where pointer arithmetic is needed. `uptr/sptr` definitions are not type safe and `void*` or `u8*` should be used for parameter passing instead, when possible.
+Note that using the C++ atomic types <code>float</code> and <code>double</code> are acceptable, and that there are no defined alternatives at this time.
-==Topic 3: Do not use `private` class members; use `protected` instead.==
+**Special note:** PCSX2-specific types <code>uptr</code> and <code>sptr</code> are meant to be integer-typed containers for pointer addresses, and should be used in situations where pointer arithmetic is needed. <code>uptr/sptr</code> definitions are not type safe and <code>void*</code> or <code>u8*</code> should be used for parameter passing instead, when possible.
-There is no justifiable reason for any class in PCSX2 to use private variable members. Private members are only useful in the context of _dynamically shared core libraries_, and only hinder the object extensibility of non-shared application code. Use `protected` for all non-public members instead, as it protects members from unwanted public access while still allowing the object to be extended into a derived class without having to waste a lot of silly effort to dance around private mess.
+==Topic 3: Do not use <code>private</code> class members; use <code>protected</code> instead.==
+There is no justifiable reason for any class in PCSX2 to use private variable members. Private members are only useful in the context of _dynamically shared core libraries_, and only hinder the object extensibility of non-shared application code. Use <code>protected</code> for all non-public members instead, as it protects members from unwanted public access while still allowing the object to be extended into a derived class without having to waste a lot of silly effort to dance around private mess.
 ==Topic 4: Name Protected Class Members with 'm_'==
-It is highly recommended to prefix protected class members with `m_`; such as `m_SomeVar` or `m_somevar`. This is a widely accepted convention that many IDEs are adding special built in support and handling for, and for that reason it can help improve class organization considerably for all contributors to the project. However, like most other guidelines it is not a definitive requirement.
+It is highly recommended to prefix protected class members with <code>m_</code>; such as <code>m_SomeVar</code> or <code>m_somevar</code>. This is a widely accepted convention that many IDEs are adding special built in support and handling for, and for that reason it can help improve class organization considerably for all contributors to the project. However, like most other guidelines it is not a definitive requirement.
 ==Topic 5: Avoid compounding complex operations onto a single line with a function declaration.==
 **Example:**
-```C++
 // Not so good...
-void DoSomething() { Function1(); Function2(); var += 1; }
+ <code>void DoSomething() { Function1(); Function2(); var += 1; }</code>
 // Good...
-void DoSomething() {
+ <code>void DoSomething() {
      Function1(); Function2();	var += 1;
 }
-```
+</code>
 The reason for this guideline is that it can assist debugging tremendously. Most C++ debuggers cannot breakpoint function calls to the bad example, disabling a programmer's ability to use the debugger to quickly track the calling patterns for a function or conditional, and thus removing one of the most ideal tools available to a programmer for understanding code execution patterns of code written by another programmer. For these reasons, code written with such compounding may likely be unrolled onto multiple lines by another programer at any time, if that programmer is tasked with troubleshooting bugs in that code.