diff --git a/02-Use_the_Tools_Available.md b/02-Use_the_Tools_Available.md index 2b6f441..83e8cb8 100644 --- a/02-Use_the_Tools_Available.md +++ b/02-Use_the_Tools_Available.md @@ -27,12 +27,12 @@ Use an industry standard widely accepted build tool. This prevents you from rein * [Waf](https://waf.io/) * [FASTBuild](http://www.fastbuild.org/) * [Ninja](https://ninja-build.org/) - Can greatly improve the incremental build time of your larger projects. Can be used as a target for CMake. - * [Bazel](http://bazel.io/) - Fast incremental builds using network artefact caching and remote execution. - * [Buck](http://buckbuild.com/) - Similar to Bazel, with very good support for iOS and Andoid. + * [Bazel](http://bazel.io/) - Fast incremental builds using network artifact caching and remote execution. + * [Buck](http://buckbuild.com/) - Similar to Bazel, with very good support for iOS and Android. * [gyp](https://chromium.googlesource.com/external/gyp/) - Google's build tool for chromium. * [maiken](https://github.com/Dekken/maiken) - Crossplatform build tool with Maven-esque configuration style. * [Qt Build Suite](http://doc.qt.io/qbs/) - Crossplatform build tool From Qt. - * [meson](http://mesonbuild.com/index.html) - Open source build system meant to be both extremely fast, and, even more importantly, as user friendly as possible. + * [meson](http://mesonbuild.com/index.html) - Open source build system meant to be both extremely fast, and, even more importantly, as user-friendly as possible. * [premake](https://premake.github.io/) * [xmake](https://xmake.io) - A cross-platform build utility based on Lua. Modern C/C++ build tools, Support multi-language hybrid compilation * [build2](https://build2.org) - A cargo-like complete toolchain (build system, package manager, project manager) @@ -49,7 +49,7 @@ Package management is an important topic in C++, with currently no clear winner. * [qpm](https://www.qpm.io/) - Package manager for Qt * [build2](https://build2.org/) - A cargo-like complete toolchain (build system, package manager, project manager) * [Buckaroo](https://buckaroo.pm) - Truly decentralized cross-platform dependency manager for C/C++ and more - * [Vcpkg](https://github.com/microsoft/vcpkg) - Microsoft C++ Library Manager for Windows, Linux, and MacOS - [description](https://docs.microsoft.com/en-us/cpp/build/vcpkg) + * [Vcpkg](https://github.com/microsoft/vcpkg) - Microsoft C++ Library Manager for Windows, Linux, and macOS - [description](https://docs.microsoft.com/en-us/cpp/build/vcpkg) * [CPM](https://github.com/cpm-cmake/CPM.cmake) - CMake package manager for modern CMake ## Continuous Integration @@ -88,7 +88,7 @@ Continuous Integration (CI) tools automatically build the source code as changes If you have an open source, publicly-hosted project on GitHub: - * go enable Travis Ci and AppVeyor integration right now. We'll wait for you to come back. For a simple example of how to enable it for your C++ CMake-based application, see here: https://github.com/ChaiScript/ChaiScript/blob/master/.travis.yml + * go enable github actions. A template for this can be found in the [C++ Boilerplate Template](https://github.com/cpp-best-practices/cmake_conan_boilerplate_template) * enable one of the coverage tools listed below (Codecov or Coveralls) * enable [Coverity Scan](https://scan.coverity.com) @@ -122,9 +122,10 @@ You should use as many compilers as you can for your platform(s). Each compiler * `-Wlogical-op` (only in GCC) warn about logical operations being used where bitwise were probably wanted * `-Wnull-dereference` (only in GCC >= 6.0) warn if a null dereference is detected * `-Wuseless-cast` (only in GCC >= 4.8) warn if you perform a cast to the same type - * `-Wdouble-promotion` (GCC >= 4.6, Clang >= 3.8) warn if `float` is implicit promoted to `double` - * `-Wformat=2` warn on security issues around functions that format output (ie `printf`) + * `-Wdouble-promotion` (GCC >= 4.6, Clang >= 3.8) warn if `float` is implicitly promoted to `double` + * `-Wformat=2` warn on security issues around functions that format output (i.e., `printf`) * `-Wlifetime` (only special branch of Clang currently) shows object lifetime issues + * `-Wimplicit-fallthrough` Warns when case statements fall-through. (Included with `-Wextra` in GCC, not in clang) Consider using `-Weverything` and disabling the few warnings you need to on Clang @@ -152,7 +153,7 @@ Consider using `-Weverything` and disabling the few warnings you need to on Clan * `/w14549` 'operator': operator before comma has no effect; did you intend 'operator'? * `/w14555` expression has no effect; expected expression with side-effect * `/w14619` pragma warning: there is no warning number 'number' - * `/w14640` Enable warning on thread un-safe static member initialization + * `/w14640` Enable warning on thread unsafe static member initialization * `/w14826` Conversion from 'type1' to 'type_2' is sign-extended. This may cause unexpected runtime behavior. * `/w14905` wide string literal cast to 'LPSTR' * `/w14906` string literal cast to 'LPWSTR' @@ -160,7 +161,8 @@ Consider using `-Weverything` and disabling the few warnings you need to on Clan Not recommended - * `/Wall` - Also warns on files included from the standard library, so it's not very useful and creates too many extra warnings. + * `/Wall` - Not recommended for normal builds because the MSVC standard library is not `/Wall` "clean", but can be enabled to discover new warnings to enable. + * Since VS2022, `/external:anglebrackets /external:W0` can be used to turn off warnings from all headers included with angle brackets, e.g. `#include `. @@ -183,7 +185,6 @@ If you are not using a build system like that, you can consider [Build EAR](http CMake now also comes with built-in support for calling `clang-tidy` during [normal compilation](https://cmake.org/cmake/help/latest/prop_tgt/LANG_CLANG_TIDY.html). * [include-what-you-use](https://github.com/include-what-you-use), [example results](https://github.com/ChaiScript/ChaiScript/commit/c0bf6ee99dac14a19530179874f6c95255fde173) - * [clang-modernize](http://clang.llvm.org/extra/clang-modernize.html), [example results](https://github.com/ChaiScript/ChaiScript/commit/6eab8ddfe154a4ebbe956a5165b390ee700fae1b) * [clang-check](http://clang.llvm.org/docs/ClangCheck.html) * [clang-tidy](http://clang.llvm.org/extra/clang-tidy.html) @@ -191,6 +192,12 @@ CMake now also comes with built-in support for calling `clang-tidy` during [norm The best bet is the static analyzer that you can run as part of your automated build system. Cppcheck and clang meet that requirement for free options. +### SonarLint / SonarQube / SonarCloud + +[SonarLint](https://www.sonarsource.com/products/sonarlint/) runs as a plug-in in all the main IDEs. The other two run as part of your build pipeline and can also gate PRs. [SonarQube](https://www.sonarsource.com/products/sonarqube/) runs on your own infrastructure whereas [SonarCloud](https://www.sonarsource.com/products/sonarcloud/) runs in The Cloud, is free for public Open Source projects and supports Automatic Analysis for zero-config setup. + +All three run the same set of analyzers (although SonarQube and SonarCloud have a handful of additional checks that are too heavyweight to run in-IDE) that catch code smells and best practice violations, as well as complex bugs. + ### Coverity Scan [Coverity](https://scan.coverity.com/) has a free (for open source) static analysis toolkit that can work on every commit in integration with [Travis CI](http://travis-ci.org) and [AppVeyor](http://www.appveyor.com/). @@ -206,7 +213,7 @@ Notes: * For correct work it requires well formed path for headers, so before usage don't forget to pass: `--check-config`. * Finding unused headers does not work with `-j` more than 1. - * Remember to add `--force` for code with a lot number of `#ifdef` if you need check all of them. + * Remember to add `--force` for code with a lot number of `#ifdef` if you need to check all of them. ### cppclean @@ -256,7 +263,11 @@ Qt Creator can plug into the clang static analyzer. ### IKOS [IKOS](https://ti.arc.nasa.gov/opensource/ikos/) is an open source static analyzer, developed by NASA. It is based on the Abstract Interpretation. It is written in C++ and provides an analyzer for C and C++, using LLVM. -The source code is [available on Github](https://github.com/NASA-SW-VnV/ikos). +The source code is [available on GitHub](https://github.com/NASA-SW-VnV/ikos). + +### codespell + +[codespell](https://github.com/codespell-project/codespell) is a spell checker for your source code. ## Runtime Checkers @@ -284,7 +295,7 @@ A coverage analysis tool shall be run when tests are executed to make sure the e * [Valgrind](http://www.valgrind.org/) * Valgrind is a runtime code analyzer that can detect memory leaks, race conditions, and other associated problems. It is supported on various Unix platforms. * [Heaptrack](https://github.com/KDE/heaptrack) - * A profiler created by a Valgrind's Massif developper. Quite similar to Massif with pros and cons over it, way more intuitive though. + * A profiler created by a Valgrind's Massif developer. Quite similar to Massif with pros and cons over it, way more intuitive though. * [Dr Memory](http://www.drmemory.org) * [Memoro](https://epfl-vlsc.github.io/memoro/) - A detailed heap profiler. @@ -333,6 +344,7 @@ These tools take code executed during unit test runs and mutate the executed cod * [MuCPP](https://neptuno.uca.es/redmine/projects/mucpp-mutation-tool/wiki) * [mull](https://github.com/mull-project/mull) * [CCMutator](https://github.com/markus-kusano/CCMutator) + * [Universal Mutator](https://github.com/agroce/universalmutator) ### Control Flow Guard @@ -350,7 +362,7 @@ Be sure to reenable the warning after disabling it for a section of code. You do ## Testing -CMake, mentioned above, has a built in framework for executing tests. Make sure whatever build system you use has a way to execute tests built in. +CMake, mentioned above, has a built-in framework for executing tests. Make sure whatever build system you use has a way to execute tests built in. To further aid in executing tests, consider a library such as [Google Test](https://github.com/google/googletest), [Catch](https://github.com/philsquared/Catch), [CppUTest](https://github.com/cpputest/cpputest) or [Boost.Test](http://www.boost.org/doc/libs/release/libs/test/) to help you organize the tests. @@ -376,6 +388,12 @@ Don't forget to make sure that your error handling is being tested and works pro [rr](http://rr-project.org/) is a free (open source) reverse debugger that supports C++. + +## Documentation Tools + + * [hdoc](https://hdoc.io/) the modern documentation tool for C++ + + ## Other Tools ### Lizard diff --git a/03-Style.md b/03-Style.md index db2c7f6..7f8607d 100644 --- a/03-Style.md +++ b/03-Style.md @@ -35,7 +35,7 @@ Every IDE and many editors have support for clang-format built in or easily inst C++ Standard Library (and other well-known C++ libraries like [Boost](http://www.boost.org/)) use these guidelines: * Macro names use upper case with underscores: `INT_MAX`. - * Template parameter names use camel case: `InputIterator`. + * Template parameter names use Pascal case: `InputIterator`. * All other names use snake case: `unordered_map`. ## Distinguish Private Object Data diff --git a/04-Considering_Safety.md b/04-Considering_Safety.md index 0592ff9..26a87bb 100644 --- a/04-Considering_Safety.md +++ b/04-Considering_Safety.md @@ -2,7 +2,7 @@ ## Const as Much as Possible -`const` tells the compiler that a variable or method is immutable. This helps the compiler optimize the code and helps the developer know if a function has a side effect. Also, using `const &` prevents the compiler from copying data unnecessarily. The [comments on `const` from John Carmack](http://kotaku.com/454293019) are also a good read. +`const` tells the compiler that a variable or method is immutable. This helps the compiler optimize the code and helps the developer know if a function has a side effect. Also, using `const &` prevents the compiler from copying data unnecessarily. The [comments on `const` from John Carmack](https://web.archive.org/web/20131211065348/https://kotaku.com/454293019) are also a good read. ```cpp // Bad Idea diff --git a/09-Considering_Correctness.md b/09-Considering_Correctness.md index 8313374..f39af90 100644 --- a/09-Considering_Correctness.md +++ b/09-Considering_Correctness.md @@ -25,4 +25,4 @@ Consider using a typesafe library like Note that stronger typing can also allow for more compiler optimizations. -* [Sorting in C vs C++](Sorting in C vs C++.pdf) +* [Sorting in C vs C++](Sorting%20in%20C%20vs%20C++.pdf)