summaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
authorJoel Rosdahl <joel@rosdahl.net>2019-07-24 13:18:17 +0200
committerJoel Rosdahl <joel@rosdahl.net>2019-08-14 21:41:28 +0200
commit68e42bd71650d003cb8f01d6572020015ecc2e58 (patch)
tree00f1cc30a983379696a8318c488aab2b50360fc6 /CONTRIBUTING.md
parentfc49e169b480c43dbe9598a64bb89b6743c3bc7e (diff)
downloadccache-68e42bd71650d003cb8f01d6572020015ecc2e58.tar.gz
C++-ify source code
The ccache source code will be converted to C++, targeting C++11. This commit only arranges the existing C-style code to be built as C++ code. This makes it possible to call new C++ code from old C-style code. Gradual conversion to C++ functionality and idioms will follow in a slow and controlled fashion – no big bang rewrites. The alternative would be to convert code in a top-down fashion, i.e. only calling legacy C code from new C++ code, not the other way around. That approach is however not a good idea since the code that will benefit most from being written in proper C++ is code deep down in the call chains. Except for renaming source code files to .cpp and .hpp, this commit makes minimal changes to make the code base buildable again, for example: - Instructs configure.ac to look for a mandatory C++11-compliant compiler. - Adds Makefile rules for building C++ code. - Sets up Travis-CI to pass C++ compiler flags and similar to the build. - Adds new casts where needed. - Adds const keywords where needed. - Renames variables to something else than C++ keywords (e.g. “template”). - Rearranges some code to avoid complaints about goto jumps that cross variable lifetimes.
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md60
1 files changed, 27 insertions, 33 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 74ba5876..27bbc93b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -34,10 +34,10 @@ proposal(s) on [GitHub](https://github.com/ccache/ccache).
Here are some hints to make the process smoother:
* If you plan to implement major changes it is wise to open an issue on GitHub
- (or send a mail to the mailing list) asking for comments on your plans before
- doing the bulk of the work. That way you can avoid potentially wasting time
- on doing something that may need major rework to be accepted, or maybe
- doesn'tend up being accepted at all.
+ (or ask in the Gitter room, or send a mail to the mailing list) asking for
+ comments on your plans before doing the bulk of the work. That way you can
+ avoid potentially wasting time on doing something that may need major rework
+ to be accepted, or maybe doesn't end up being accepted at all.
* Is your pull request "work in progress", i.e. you don't think that it's ready
for merging yet but you want early comments? Then create a draft pull request
as described in [this Github blog
@@ -48,41 +48,35 @@ Here are some hints to make the process smoother:
Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
when writing commit messages.
-### Code style
+## Code style
-#### Formatting
+ccache was written in C99 until 2019 when it started being converted to C++11.
+The conversion is a slow work in progress, which is why there are lots of
+C-style code left. Please refrain from doing large C to C++ conversions at
+once; do it little by little.
-* Use tabs for indenting and spaces for aligning C code.
-* Use 4 spaces for indenting other code (and spaces for aligning).
-* Put the opening curly brace on a new line when defining a function, otherwise
- at the end of the same line.
-* Put no space between function name and the following parenthesis.
-* Put one space between if/switch/for/while/do and opening curly brace.
-* Always use curly braces around if/for/while/do bodies, even if they only
- contain one statement.
+Tip: Install the tool [Uncrustify(http://uncrustify.sourceforge.net) and then
+run `make uncrustify` to fix up source code formatting.
+
+### New code
+
+* Use tabs for indenting and spaces for aligning.
* If possible, keep lines at most 80 character wide for a 2 character tab
width.
-* Use only lowercase names for functions and variables.
-* Use only uppercase names for enum items and (with some exceptions) macros.
-* Don't use typedefs for structs and enums.
-* Use //-style comments.
+* Put the opening curly brace on a new line when defining a class, struct or
+ function, otherwise at the end of the same line.
+* Use UpperCamelCase for classes, structs, functions, methods, members and
+ global variables.
+* Use lowerCamelCase for parameters, arguments and local variables.
+* Use UPPER_CASE names for macros.
-Tip: Install the tool [Uncrustify(http://uncrustify.sourceforge.net) and then
-run `make uncrustify` to fix up source code formatting.
+### Legacy C-style code style
-#### Idioms
-
-* Declare variables as late as convenient, not necessarily at the beginning of
- the scope.
-* Use NULL to initialize null pointers.
-* Don't use NULL when comparing pointers.
-* Use format(), x_malloc() and friends instead of checking for memory
- allocation failure explicitly.
-* Use str_eq() instead of strcmp() when testing for string (in)equality.
-* Consider using str_startswith() instead of strncmp().
-* Use bool, true and false for boolean values.
-* Use tmp_unlink() or x_unlink() instead of unlink().
-* Use x_rename() instead of rename().
+* Put the opening curly brace on a new line when defining a function, otherwise
+ at the end of the same line.
+* Put no space between function name and the following parenthesis.
+* Use UPPER_CASE names for enum values and macros.
+* Use snake_case for everything else.
#### Other