Changes between Version 22 and Version 23 of BestPracticeHandbook

Timestamp:

May 13, 2015, 11:45:40 PM (7 years ago)

Author:

Niall Douglas

Comment:

--

BestPracticeHandbook

@@ -263 +263 @@
 == 5. QUALITY: Strongly consider per-commit compiling your code with static analysis tools ==
 
-In Travis and Appveyor it is easy to configure a special build job which uses the clang static analyser on Linux/OS X and the MSVC static analyser on Windows. These perform lengthy additional static AST analysis tests to detect when your code is doing something stupid and the use of these is an excellent sign that the developer cares about code quality. Static analysis is perfectly suited to be run by a CI as it takes extra time to compile your program, so a CI can trundle off and do the lengthy work itself while you get on with other work.
+In Travis and Appveyor it is easy to configure a special build job which uses the clang static analyser and clang lint tools on Linux/OS X and the MSVC static analyser on Windows. These perform lengthy additional static AST analysis tests to detect when your code is doing something stupid and the use of these is an excellent sign that the developer cares about code quality. Static analysis is perfectly suited to be run by a CI as it takes extra time to compile your program, so a CI can trundle off and do the lengthy work itself while you get on with other work.
 
 Enabling Microsoft's static analyser is easy, simply add /analyze to the compiler command line. Your compile will take ten times longer and new warnings will appear. Note though that the MSVC static analyser is quite prone to false positives like miscounting array entries consumed. You can suppress those using the standard #pragma warning(disable: XXX) system around the offending code.
@@ -286 +286 @@
 
 scan-build will generate a HTML report of the issues found with a pretty graphical display of the logic followed by the analyser into the $REPORTS directory. Jenkins has a plugin which can publish this HTML report for you per build, for other CIs you'll need to copy the generated files onto a website somewhere e.g. committing them to your repo under gh-pages and pushing them back to github.
+
+Finally, the clang lint tool (called [http://clang.llvm.org/extra/clang-tidy.html clang-tidy]) is not something I have currently enabled in my own code, but it looks very promising. The following checks are default enabled on clang tidy 3.6:
+
+{{{
+Enabled checks:
+    clang-analyzer-core.CallAndMessage
+    clang-analyzer-core.DivideZero
+    clang-analyzer-core.DynamicTypePropagation
+    clang-analyzer-core.NonNullParamChecker
+    clang-analyzer-core.NullDereference
+    clang-analyzer-core.StackAddressEscape
+    clang-analyzer-core.UndefinedBinaryOperatorResult
+    clang-analyzer-core.VLASize
+    clang-analyzer-core.builtin.BuiltinFunctions
+    clang-analyzer-core.builtin.NoReturnFunctions
+    clang-analyzer-core.uninitialized.ArraySubscript
+    clang-analyzer-core.uninitialized.Assign
+    clang-analyzer-core.uninitialized.Branch
+    clang-analyzer-core.uninitialized.CapturedBlockVariable
+    clang-analyzer-core.uninitialized.UndefReturn
+    clang-analyzer-cplusplus.NewDelete
+    clang-analyzer-cplusplus.NewDeleteLeaks
+    clang-analyzer-deadcode.DeadStores
+    clang-analyzer-llvm.Conventions
+    clang-analyzer-security.FloatLoopCounter
+    clang-analyzer-security.insecureAPI.UncheckedReturn
+    clang-analyzer-security.insecureAPI.getpw
+    clang-analyzer-security.insecureAPI.gets
+    clang-analyzer-security.insecureAPI.mkstemp
+    clang-analyzer-security.insecureAPI.mktemp
+    clang-analyzer-security.insecureAPI.rand
+    clang-analyzer-security.insecureAPI.strcpy
+    clang-analyzer-security.insecureAPI.vfork
+    clang-analyzer-unix.API
+    clang-analyzer-unix.Malloc
+    clang-analyzer-unix.MallocSizeof
+    clang-analyzer-unix.MismatchedDeallocator
+    clang-analyzer-unix.cstring.BadSizeArg
+    clang-analyzer-unix.cstring.NullArg
+}}}
+
+I also see some default disabled checks which might be interesting:
+
+{{{
+    clang-analyzer-alpha.core.BoolAssignment
+    clang-analyzer-alpha.core.CallAndMessageUnInitRefArg
+    clang-analyzer-alpha.core.CastSize
+    clang-analyzer-alpha.core.CastToStruct
+    clang-analyzer-alpha.core.FixedAddr
+    clang-analyzer-alpha.core.IdenticalExpr
+    clang-analyzer-alpha.core.PointerArithm
+    clang-analyzer-alpha.core.PointerSub
+    clang-analyzer-alpha.core.SizeofPtr
+    clang-analyzer-alpha.core.TestAfterDivZero
+    clang-analyzer-alpha.cplusplus.VirtualCall
+    clang-analyzer-alpha.deadcode.UnreachableCode
+    misc-argument-comment
+    misc-bool-pointer-implicit-conversion
+    misc-swapped-arguments
+    misc-undelegated-constructor
+    misc-uniqueptr-reset-release
+    misc-unused-raii
+    misc-use-override
+    readability-braces-around-statements
+    readability-function-size
+    readability-redundant-smartptr-get
+}}}
 
 
@@ -865 +932 @@
 == 15. BUILD: Consider defaulting to header only, but actively manage facilities for reducing build times ==
 
+Making your library header only is incredibly convenient for your users - they simply drop in a copy of your project and get to work, no build system worries. Hence most Boost libraries and many C++ libraries are header only capable, often header only default. A minority are even header only only.
+
+One thing noticed in the library review is just how many of the new C++ 11/14 libraries are header only only, and whilst convenient I think library authors should and moreover ''can'' do better. For some statistics to put this in perspective, proposed Boost.AFIO v1.3 provides a range of build configurations for its unit tests:
+
+1. Header only
+2. Precompiled header only (default)
+3. Precompiled not header only (library implementation put into a shared library)
+4. Precompiled header only with link time optimisation
+
 ||= Build flags =||= Microsoft Windows 8.1 x64 with Visual Studio 2013 =||= Ubuntu 14.04 LTS Linux x64 with GCC 4.9 and gold linker =||= Ubuntu 14.04 LTS Linux x64 with clang 3.4 and gold linker =||
 || Debug header only                   ||  7m17s || 12m0s  || 5m45s ||
+|| Debug precompiled header only       ||  2m10s || 10m26s || 5m46s ||
 || Debug precompiled not header only   ||  0m55s ||  3m53s || asio failure ||
+|| Release precompiled header only     ||  2m58s ||  9m57s || 8m10s ||
 || Release precompiled not header only ||  1m10s ||  3m22s || asio failure ||
-|| Debug precompiled header only       ||  2m10s || 10m26s || 5m46s ||
-|| Release precompiled header only     ||  2m58s ||  9m57s || 8m10s ||
-|| Debug precompiled header only link time optimisation    || 5m37s || GCC ICE ||  5m42s ||
 || Release precompiled header only link time optimisation  || 7m30s || 13m0s   ||  8m11s ||
+
+These are for a single core 3.9Ghz i7-3770K computer. I think the results speak for themselves, and note that AFIO is only 8k lines with not much metaprogramming.
+
+The approaches for improving build times for your library users are generally as follows:
+
+TODO
 
 == 16. COUPLING: Consider allowing your library users to dependency inject your dependencies on other libraries ==