From 5c7340061daa7c7d310f08a9c92368ed2430af04 Mon Sep 17 00:00:00 2001 From: Jason Turner Date: Mon, 8 Jun 2015 10:44:17 -0600 Subject: [PATCH] Add a new section on maintainability --- 00-Table_of_Contents.md | 13 +++++---- 03-Style.md | 22 ++------------- 05-Considering_Maintainability.md | 28 +++++++++++++++++++ ...bility.md => 06-Considering_Portability.md | 0 ...lity.md => 07-Considering_Threadability.md | 0 ...rmance.md => 08-Considering_Performance.md | 0 ...ble_Scripting.md => 09-Enable_Scripting.md | 0 ...urther_Reading.md => 10-Further_Reading.md | 0 10-Final_Thoughts.md => 11-Final_Thoughts.md | 0 9 files changed, 37 insertions(+), 26 deletions(-) create mode 100644 05-Considering_Maintainability.md rename 05-Considering_Portability.md => 06-Considering_Portability.md (100%) rename 06-Considering_Threadability.md => 07-Considering_Threadability.md (100%) rename 07-Considering_Performance.md => 08-Considering_Performance.md (100%) rename 08-Enable_Scripting.md => 09-Enable_Scripting.md (100%) rename 09-Further_Reading.md => 10-Further_Reading.md (100%) rename 10-Final_Thoughts.md => 11-Final_Thoughts.md (100%) diff --git a/00-Table_of_Contents.md b/00-Table_of_Contents.md index 4d27c8e..2246a46 100644 --- a/00-Table_of_Contents.md +++ b/00-Table_of_Contents.md @@ -3,11 +3,12 @@ 2. [Use the Tools Available](02-Use_the_Tools_Available.md) 3. [Style](03-Style.md) 4. [Considering Safety](04-Considering_Safety.md) - 5. [Considering Portability](05-Considering_Portability.md) - 6. [Considering Threadability](06-Considering_Threadability.md) - 7. [Considering Performance](07-Considering_Performance.md) - 8. [Enable Scripting](08-Enable_Scripting.md) - 9. [Further Reading](09-Further_Reading.md) - 10. [Final Thoughts](10-Final_Thoughts.md) + 5. [Considering Maintainability](05-Considering_Maintainability.md) + 6. [Considering Portability](06-Considering_Portability.md) + 7. [Considering Threadability](07-Considering_Threadability.md) + 8. [Considering Performance](08-Considering_Performance.md) + 9. [Enable Scripting](09-Enable_Scripting.md) + 10. [Further Reading](10-Further_Reading.md) + 11. [Final Thoughts](11-Final_Thoughts.md) diff --git a/03-Style.md b/03-Style.md index 58e9393..07ae0fb 100644 --- a/03-Style.md +++ b/03-Style.md @@ -271,31 +271,13 @@ Forgetting to initialize a member is a source of undefined behavior bugs which a There is almost never a reason to declare an identifier in the global namespaces. Instead, functions and classes should exist in an appropriately named namespace or in a class inside of a namespace. Identifiers which are placed in the global namespace risk conflicting with identifiers from other libraries (mostly C, which doesn't have namespaces). -## Avoid Compiler Macros - -Compiler definitions and macros are replaced by the preprocessor before the compiler is ever run. This can make debugging very difficult because the debugger doesn't know where the source came from. - -```cpp -// Bad Idea -#define PI 3.14159; - -// Good Idea -namespace my_project { - class Constants { - public: - // if the above macro would be expanded, then the following line would be: - // static const double 3.14159 = 3.14159; - // which leads to a compile-time error. Sometimes such errors are hard to understand. - static const double PI = 3.14159; - } -} -``` - ## Use the Correct Integer Type For stdlib Features The standard library generally returns `size_t` for anything related to size. What exactly `size_t` is is implementation defined. +In general, using `auto` will avoid most of these issues, but not all. + Make sure you stick with the correct integer types and remain consistent with the C++ stdlib. It might not warn on the platform you are currently using, but it probably will when you change platforms. ## Use .hpp and .cpp for Your File Extensions diff --git a/05-Considering_Maintainability.md b/05-Considering_Maintainability.md new file mode 100644 index 0000000..54183b2 --- /dev/null +++ b/05-Considering_Maintainability.md @@ -0,0 +1,28 @@ +# Considering Maintainability + + +## Avoid Compiler Macros + +Compiler definitions and macros are replaced by the preprocessor before the compiler is ever run. This can make debugging very difficult because the debugger doesn't know where the source came from. + +```cpp +// Bad Idea +#define PI 3.14159; + +// Good Idea +namespace my_project { + class Constants { + public: + // if the above macro would be expanded, then the following line would be: + // static const double 3.14159 = 3.14159; + // which leads to a compile-time error. Sometimes such errors are hard to understand. + static const double PI = 3.14159; + } +} +``` + + + +## Avoid Raw Loops + +Know and understand the existing C++ standard algorithms and put them to use. See [C++ Seasoning](https://www.youtube.com/watch?v=qH6sSOr-yk8) for more details. diff --git a/05-Considering_Portability.md b/06-Considering_Portability.md similarity index 100% rename from 05-Considering_Portability.md rename to 06-Considering_Portability.md diff --git a/06-Considering_Threadability.md b/07-Considering_Threadability.md similarity index 100% rename from 06-Considering_Threadability.md rename to 07-Considering_Threadability.md diff --git a/07-Considering_Performance.md b/08-Considering_Performance.md similarity index 100% rename from 07-Considering_Performance.md rename to 08-Considering_Performance.md diff --git a/08-Enable_Scripting.md b/09-Enable_Scripting.md similarity index 100% rename from 08-Enable_Scripting.md rename to 09-Enable_Scripting.md diff --git a/09-Further_Reading.md b/10-Further_Reading.md similarity index 100% rename from 09-Further_Reading.md rename to 10-Further_Reading.md diff --git a/10-Final_Thoughts.md b/11-Final_Thoughts.md similarity index 100% rename from 10-Final_Thoughts.md rename to 11-Final_Thoughts.md