diff --git a/styleguide/cppguide.html b/styleguide/cppguide.html index a603baa632..f37c836c1d 100644 --- a/styleguide/cppguide.html +++ b/styleguide/cppguide.html @@ -15,10 +15,22 @@
This guide is a work in progress. +We are currently working on getting this guide updated to +a point where it is useful for WPILib developers to use.
+C++ is one of the two main languages (Java being the other) used in WPILib; in order to maintain consistency and keep the maintenance of the code manageable, we use this style guide.
+There are two main overarching purposes to this guide. The first +is to act as a normal C++ style guide (both in terms fo formatting +and programming practices) for C++ developers of WPILib. +The other purpose is to help Java programmers who may +know a moderate amount of C++ but may not be fully +up to date with things like C++11 and so may not even +realize that certain C++ features exist.
+This style guide is a heavily modified version of the Google C++ Style Guide. The Google Style Guide has @@ -81,6 +93,83 @@ use your judgement and ask others in cases where there is something which may violate anything in this guide.
+C++ is a large, complicated language, and in order +to ensure that we stay consistent and maintain certain +best practices, we have certain rules. For the most part +these are common sense rules and in some cases exist +solely to point out features of C++ that someone more +familiar with Java may not realize even exist.
+ +In general, we strongly discourage the use of +raw pointers in C++ code; instead, references or +STL pointers should be used where appropriate. +There are two exceptions to this rule:
+[[deprecated]]
+ attribute and replaced with either references
+ or STL pointers.As of C++11, the following are options in the +place of raw pointers:
+std::unique_ptr Should be used
+ when you still need to use a pointer, but you
+ only need one entity to own the pointer. The
+ std::unique_ptr will automatically
+ be deleted when there are no more references to
+ it.std::shared_ptr Should be used
+ when you still need to use a pointer and you
+ need many references to the object. When
+ there are zero remaining references to the
+ object, it will be deleted. Use std::weak_ptr
+ where necessary to avoid circular dependencies
+ or other potential issues.std::move.
+ R-value references should be used where it makes
+ sense that a parameter to a function is having
+ its ownership passed from one place to another.
+ In general, R-value references are not inherently
+ bad, but they do introduce additional complexity
+ that may confuse people who are not familiar
+ with them.When updating APIs, make liberal use of the
+[[deprecated]] attribute (although if
+it is reasonable to simply remove any old interfaces
+then do so) to indicate that users should no longer
+use the function. Currently, this will cause warnings
+in user code and errors in the WPILib build.
+[[deprecated("This is a deprecated function; this text will be displayed when"
+ " the compiler throws a warning.")]]
+void foo() {}
+class [[deprecated("This is a deprecated class.")]] Foo {};
+int bar [[deprecated("This is a deprecated variable.")]];
+
+
+See +here for more information on deprecation.
This guide is a work in progress. +We are currently working on getting this guide updated to +a point where it is useful for WPILib developers to use.
+This document serves as the style guide for WPILib. It is heavily based on the Google Java Style Guide and copies pretty much word-for-word the formatting/style components of the guide while cutting a couple