doc: Formatting and tweaks to style guide.

Of particular note:

1. I added two exceptions regarding template parameter names: `scalar` and
   `time` don't need a T.

2. I removed `m_` from class variables.

Signed-off-by: Matthew Emmett <[email protected]>

Author: memmett

doc/source/contributing.md

@@ -2,50 +2,59 @@
 
 ## Branching and Tagging Model
 
-We use the [git-flow] workflow to that extend, that branch names(paces) have a certain meaing:
+We use the [git-flow] workflow to that extend, that branch
+names(paces) have a certain meaing:
 
 Branch Name Pattern | Description
---------------------|-------------
+--------------------|------------
 `master`            | tip of the `master` branch is always the latest stable release
 `development`       | tip of the `development` branch is the current state of development and not expected to be stable or even usable
 `feature/*`         | various feature branches are used to implement new features and should be based off the `development` branch
 `release/*`         | a release branch is created from the `development` branch and used to prepare a new release and will be merged into `master`
 `hotfix/*`          | hotfix branches are based off `master` or `development` to fix important and severe bugs and should be merged into `development` and `master` as soon as possible
 
-Releases and release candidates are tagged in the form `release-X.Y.Z(-RCa)`, where `X`, `Y`, and `Z` specify
-the version with respect to [semantic versioning] and `a` the number of the release candidate of that version.
+Releases and release candidates are tagged in the form
+`release-X.Y.Z(-RCa)`, where `X`, `Y`, and `Z` specify the version
+with respect to [semantic versioning] and `a` the number of the
+release candidate of that version.
 
 
 ## Commit Messages
 
-To ease browsing the proejct's history, we try to keep our commit messages clean and descriptive.
-Please try to follow the following rules as best as possible:
+To ease browsing the proejct's history, we try to keep our commit
+messages clean and descriptive.  Please try to follow the following
+rules as best as possible:
 
 * Commit Title must not be longer than 50 characters
 
-  If applicable, the title should start with a category name (such as `docu`, `tests`, ...)
-  followed by a colon (e.g. `"docu: add usage examples for plain SDC"` ).
+  If applicable, the title should start with a category name (such as
+  `docu`, `tests`, ...)  followed by a colon (e.g. `"docu: add usage
+  examples for plain SDC"` ).
 
 * Commit Description must have line wraps at 72 characters
 
 * Please *sign* your commits (i.e. use `git commit -s`)
 
-  This automatically appends a line of the form `"Signed-off-by: Torbjörn Klatt <[email protected]>"` to the end
-  of the commit message.
+  This automatically appends a line of the form `"Signed-off-by:
+  Torbjörn Klatt <[email protected]>"` to the end of the commit
+  message.
 
 
 ## How to Implement a New Feature?
 
 -# create a fork/clone
 -# switch to the `development` branch and pull in the latest changes
--# create a new branch `feature/XYZ` where `XYZ` is a short title of your planned feature
-   (word seperation should be done with underscores, e.g. `feature/my_awesome_feature`)
+-# create a new branch `feature/XYZ` where `XYZ` is a short title of
+   your planned feature (word seperation should be done with
+   underscores, e.g. `feature/my_awesome_feature`)
 -# hack and write Unit Tests
 -# commit
--# repeat steps 4 and 5 until you feel your feature is in an almost usable state and most of the unit tests pass
+-# repeat steps 4 and 5 until you feel your feature is in an almost
+   usable state and most of the unit tests pass
 -# write documentation for your feature
 -# push your feature branch
--# stay tuned on reviews, remarks and suggestions by the other developers
+-# stay tuned on reviews, remarks and suggestions by the other
+   developers
 
 
 [git-flow]: http://nvie.com/posts/a-successful-git-branching-model/

doc/source/style_guide.md

@@ -1,23 +1,21 @@
 # Style Guide
 
-To ease development we agree on a basic code style described as follows.
-
 ## Naming Convention
 
-In general, abbreviations should only be used if they are absolutely unambigious and would save a
-lot of horizontal space.
-In case one hesitates whether to abbreviate a variable or not, rather not do it!
+In general, abbreviations should only be used if they are absolutely
+unambigious and would save a lot of horizontal space.
 
-Always use underscores (`_`) as word separation.
+Always use underscores (`_`) to separate words.
 
 * __Files__
 
-  Due to systems which do not distinguish between upper and lower case in file and path names,
-  always use lowercase for file names and directories.
+  To accomodate systems which do not distinguish between upper and
+  lower case in file and path names, always use lowercase for file
+  names and directories.
 
-  Header files should be named after the main/central class contained in.
-  For example, a class `MyClass` should be in a header file called `my_header.hpp`.
-  Separate words by underscores.
+  Header files should be named after the main/central class that they
+  contain.  For example, a class `MyClass` should be in a header file
+  called `my_header.hpp`.  Separate words by underscores.
 
 * __Namespaces__
 
@@ -26,50 +24,47 @@ Always use underscores (`_`) as word separation.
 * __Class Names__
 
   Should start with a capital letter and use _CamelCase_.
-  
-  Abstract classes should start with a capital `I` denoting an _interface_. E.g. `ISweeper` in 
-  `i_sweeper.hpp`.
+
+  Abstract classes should start with a capital `I` denoting an
+  _interface_.  For example, `ISweeper`.
 
 * __Function Names__
 
-  Should only consist of lowercase letters and underscores separating words.
+  Should always be lowercase.
 
 * __Variable Names__
 
-  Should always be lowercase using underscores as word separation.
-  Member variables of classes should start with `m_`.
-  Constants should all be uppercase with undersocres as word separation.
+  Should always be lowercase.  Constants should all be uppercase with
+  undersocres as word separation.
 
-* __Template Parameter__
+* __Template Parameters__
 
-  In case, most template parameters denote a certain type, append a capital `T` to the name of the
-  template parameter. E.g.
+  When template parameters refer to a type name, append a capital `T`
+  to the name of the template parameter.  For example
   ~~~{.cpp}
   template<typename typeT>
   int my_func(std::vector<typeT> &vec);
   ~~~
 
+  Acceptable exceptions to this rule are `scalar` (which denotes a
+  spatial type, e.g. `complex<double>`) and `time` (which denotes a
+  temporal type, e.g. `double`).
+
 
 ## Techniques
 
 ### Includes
 
-System headers and those from third party libraries should be included using angular brackets.
-Headers from our library should be included using double quotes.
-
-For headers included via angular brackets, the preprocessor will search through all paths given via
-the `-I` parameter.
-While for includes with double quotes it will only look in the directory of the header including
-the included file.
-Only when there is no such header in there, the preprocessor will go on with the behaviour for 
-angular brackets.
+System headers and those from third party libraries should be included
+using angular brackets.  Headers from our library should be included
+using double quotes.
 
 ### Define Guards
 
 Use `#define` guards in header files to prevent multiple inclusion.
-The variable defined should be derived from the header file name itself.
-For example, a header file `my_header.hpp` in the folder `PFASST/src/subfolder` should have the 
-following define guard:
+The variable defined should be derived from the header file name
+itself.  For example, a header file `my_header.hpp` in the folder
+`PFASST/include/subfolder` should have the following define guard:
 
 ~~~{.cpp}
 #ifndef PFASST__SUBFOLDER__MY_HEADER_HPP
@@ -78,19 +73,19 @@ following define guard:
 #endif // PFASST__SUBFOLDER__MY_HEADER_HPP
 ~~~
 
-Always include the library name and at least one subfolder (if applicable) to prevent possible 
-multiple defines in files with the same name but in different folders.
+Always include the library name and at least one subfolder (if
+applicable) to prevent multiple defines in files with the same name
+but in different folders.
 
 ### Encapsulation / Clean API
 
-We want to provide a clean API, thus we use encapsulation wherever possible.
-For classes, we prefer private member/data variables and provide access to them via getter/setter
-methods.
+We want to provide a clean API, thus we use encapsulation wherever
+possible.  For classes, we prefer private member/data variables and
+provide access to them via getter/setter methods.
 
 ### C++ Feature Set
 
-We agreed on using the "most common" C++11 features.
-These are:
+We agreed on using the "most common" C++11 features.  These are:
 
 * `auto` keyword
 * `shared_ptr` and `unique_ptr`
@@ -102,25 +97,25 @@ These are:
 * `constexpr`
 * right angle bracket (`vector<vector<T> >` vs. `<vector<vector<T>>`)
 
-@todo Check the list of used/required C++11 features and possibly extend it by a list of minimum 
+@todo Check the list of used/required C++11 features and possibly extend it by a list of minimum
   compiler versions supporting the features.
 
 
 ## Documentation
 
 Document your code.
 
-We use [Doxygen] for generating the documentation webpage.
-You can use pretty much all the features, Doxygen provides, including [MathJAX] for formulas and 
-[Markdown] for easy text formatting.
-
+We use [Doxygen] for generating the documentation webpage.  You can
+use pretty much all the features, Doxygen provides, including
+[MathJAX] for formulas and [Markdown] for easy text formatting.
 
 ## Formatting
 
 In short: no tabs, 2 spaces, sane indent-continuation.
 
-We provide a configuration file for the code beautifier [uncrustify] which does a pretty good job
-to ensure consistent formatting of the source files.
+We provide a configuration file for the code beautifier [uncrustify]
+which does a pretty good job to ensure consistent formatting of the
+source files.
 
 
 [Doxygen]: http://www.stack.nl/~dimitri/doxygen/index.html