Re: Need help with improving package descriptions for Cppcheck
Reijo Tomperi wrote:
> I'm the maintainer of Cppcheck package and I recently got a bug report
> about the description and as I'm not a technical writer, nor am I native
> English speaker, I'm requestiong help to improve the description.
I'm a NES, but I'll really need some advice from C/C++ experts.
> The current description is "This program tries to detect bugs that your
> C/C++ compiler don't see. The goal is no false positives. Your compiler
> can detect many problems that Cppcheck don't try to detect. Cppcheck is
> versatile. You can check non-standard code that includes various
> compiler extensions, inline assembly code, etc. "
> http://packages.debian.org/sid/cppcheck
There are a couple of grammatical errors there (s/don't/doesn't/g),
and it would read more smoothly if it was reorganised slightly; maybe:
This program tries to detect bugs that your C/C++ compiler doesn't see
(while your compiler can detect many problems that Cppcheck doesn't).
Cppcheck is versatile, and can check non-standard code that includes
various compiler extensions, inline assembly code, etc.
> The program description in upstream site starts like this, but there is
> quite a lot of additional information:
> "Cppcheck is an analysis tool for C/C++ code. Unlike C/C++ compilers and
> many other analysis tools, we don't detect syntax errors. Cppcheck only
> detects the types of bugs that the compilers normally fail to detect.
> The goal is no false positives. "
> http://sourceforge.net/apps/mediawiki/cppcheck/index.php?title=Main_Page
That's a smoother way of phrasing it, but obviously upstream-ese -
the package description can't say "we". (Is that where the "don't"s
came from?)
> A short list about this program which I think could be used to build up
> the description:
> - It is for C and C++ programmers and people who tests programs written
> in those languages.
>
> - It is a command line application (there is also a GUI, but it is not
> yet packaged for Debian nor do I have plans to package it at the moment
> due to lack of time and no-one has requested it) for static code
> analysis of C or C++ source code.
>
> - It can find real bugs from the source code. The kind of bugs that can
> cause e.g. program to crash, misbehave or leak memory.
The existing description seems to convey this much pretty well,
though maybe it should include "command line".
> - It stands out (or at leasts tries to) from other similar tools by
> having a low amount of false positives
Can you name some rivals that aim to have, say, 50% false positives?
I'm not really convinced by this.
> - It also stands out from some of the tools by not requiring valid
> syntax and it is possible to check code which uses 3rd party libraries,
> non-standard compiler extensions etc.
>
> - There is also a list of checks which can be mentioned by name (see the
> upstream web site for full list), which should perhaps be mentioned in
> the long description. But again I'm not sure how to format the list and
> should all be mentioned or just something?
>
> Thanks for any help or advice you can give.
Well, looking at the full description in the control file:
| Description: Tool for static C/C++ code analysis
This would be fully DevRef compliant if "tool" was lowercase.
| This program tries to detect bugs that your C/C++ compiler don't see.
| The goal is no false positives.
| Your compiler can detect many problems that Cppcheck don't try to detect.
| Cppcheck is versatile. You can check non-standard code that includes various
| compiler extensions, inline assembly code, etc.
| * -- Checks
| * - Auto Variables
The formatting here doesn't really work. I'd suggest just making it
a single flat list.
| * Auto variables are deallocated when they go out of scope. A pointer to an
| auto variable is therefore only valid as long as the auto variable is in
| scope. Check:
| * returning a pointer to auto variable
I don't follow the details... is that all one check?
| * assignment of an auto-variable to an effective parameter of a function
It looks as if all of this so far could be boiled down to:
It includes checks for:
* pointers to out-of-scope auto variables;
* assignment of auto variables to an effective parameter of a function;
| * - Bounds checking
| * out of bounds checking
The repetition here doesn't seem to achieve much. Could you just
say it's a check for:
* out-of-bounds arrays;
| * - Class
| * Check the code for each class.
Er, what? I'd just drop this.
| * Missing constructors
* missing class constructors;
| * Are all variables initialized by the constructors?
Rephrase them consistently as the thing being checked for:
* variables not initialized by a constructor;
| * Warn if memset, memcpy etc are used on a class
* use of memset, memcpy, etcetera on a class;
| * If it's a base class, check that the destructor is virtual
* non-virtual destructors for base classes;
| * The operator= should return a constant reference to itself
* failure of the = operator to return a constant reference to itself;
| * Are there unused private functions
* unused private functions;
| * - Deprecated functions
| * Warn if any of these deprecated functions are used:
| * mktemp
| * gets
| * scanf
All of this could be boiled down to:
* use of deprecated functions (mktemp, gets, scanf);
| * - Exception safety
| * Checking exception safety
Two lines of subsection header again,
| * Don't throw exceptions in destructors
* exceptions thrown in destructors;
| * - Memory leaks (function variables)
| * Is there any allocated memory when a function goes out of scope
| * - Memory leaks (class variables)
| * If the constructor allocate memory then the destructor must deallocate it.
Uh, I think that would be:
* memory leaks in class or function variables;
| * - Other
| * Other checks
(Why is the miscellaneous-odds-and-ends subsection in the middle?)
| * C-style pointer cast in cpp file
Should that be "C++"? If not, it'll be fine as it is.
| * redundant if
Fair enough - though lower down there's "condition that is always
true/false". Aren't these talking about the same thing? That is:
* redundant conditions
| * bad usage of the function 'strtol'
| * bad usage of the function 'sprintf' (overlapping data)
Merge as:
* misuse of the strtol or sprintf functions;
| * division with zero
| * unsigned division
Merge as:
* unsigned division or division by zero;
| * unused struct member
I'm not sure what that means, but I'd repunctuate it as:
* unused struct members;
| * passing parameter by value
* passing parameters by value;
| * check how signed char variables are used
"Check" is redundant. But since I don't know what the wrong way of
using them is, I'll have to say:
* misuse of signed char variables;
(Maybe it should go up after "misuse of the strtol or sprintf
functions".)
| * condition that is always true/false
Mentioned above.
| * unusual pointer arithmetic. For example: "abc" + 'd'
I don't understand this (are the different quotation styles
significant?), but I can rephrase it:
* unusual pointer arithmetic (such as "abc" + 'd');
| * dereferencing a null pointer
| * Incomplete statement
For consistency,
* dereferenced null pointers;
* incomplete statements;
| * optimisation: detect post increment/decrement
I don't understand this, but it doesn't sound like a category of
problem that cppcheck tests for. Should it perhaps be mentioned
outside the list of checks?
| * - STL usage
| * Check for invalid usage of STL:
Another redundant section-header.
| * out of bounds errors
Wait, didn't we have that? Maybe say:
* out of bounds errors in STL;
| * misuse of iterators when iterating through a container
| * dereferencing an erased iterator
* misuse of iterators when iterating through a container;
* dereferencing of erased iterators;
| * for vectors: using iterator/pointer after push_back has been used
| * dangerous usage of find
These are very specific checks of some sort I really don't
understand. Can I just skip them, please? It's not as if there's a
shortage.
| * optimisation: using empty() instead of size()
Another not-exactly-a-check check.
| * - Unused functions
| * Check for functions that are never called
* functions that are never called.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
--- control.old 2010-01-31 10:31:15.000000000 +0000
+++ control.new 2010-02-01 21:35:07.000000000 +0000
@@ -9,66 +9,35 @@
Package: cppcheck
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
-Description: Tool for static C/C++ code analysis
- This program tries to detect bugs that your C/C++ compiler don't see.
- The goal is no false positives.
- Your compiler can detect many problems that Cppcheck don't try to detect.
- Cppcheck is versatile. You can check non-standard code that includes various
- compiler extensions, inline assembly code, etc.
- * -- Checks
- * - Auto Variables
- * Auto variables are deallocated when they go out of scope. A pointer to an
- auto variable is therefore only valid as long as the auto variable is in
- scope. Check:
- * returning a pointer to auto variable
- * assignment of an auto-variable to an effective parameter of a function
- * - Bounds checking
- * out of bounds checking
- * - Class
- * Check the code for each class.
- * Missing constructors
- * Are all variables initialized by the constructors?
- * Warn if memset, memcpy etc are used on a class
- * If it's a base class, check that the destructor is virtual
- * The operator= should return a constant reference to itself
- * Are there unused private functions
- * - Deprecated functions
- * Warn if any of these deprecated functions are used:
- * mktemp
- * gets
- * scanf
- * - Exception safety
- * Checking exception safety
- * Don't throw exceptions in destructors
- * - Memory leaks (function variables)
- * Is there any allocated memory when a function goes out of scope
- * - Memory leaks (class variables)
- * If the constructor allocate memory then the destructor must deallocate it.
- * - Other
- * Other checks
- * C-style pointer cast in cpp file
- * redundant if
- * bad usage of the function 'strtol'
- * bad usage of the function 'sprintf' (overlapping data)
- * division with zero
- * unsigned division
- * unused struct member
- * passing parameter by value
- * check how signed char variables are used
- * condition that is always true/false
- * unusual pointer arithmetic. For example: "abc" + 'd'
- * dereferencing a null pointer
- * Incomplete statement
- * optimisation: detect post increment/decrement
- * - STL usage
- * Check for invalid usage of STL:
- * out of bounds errors
- * misuse of iterators when iterating through a container
- * dereferencing an erased iterator
- * for vectors: using iterator/pointer after push_back has been used
- * dangerous usage of find
- * optimisation: using empty() instead of size()
- * - Unused functions
- * Check for functions that are never called
-
-
+Description: tool for static C/C++ code analysis
+ This program tries to detect bugs that your C/C++ compiler doesn't see
+ (while your compiler can detect many problems that Cppcheck doesn't).
+ Cppcheck is versatile, and can check non-standard code that includes
+ various compiler extensions, inline assembly code, etc.
+ .
+ It includes checks for:
+ * pointers to out-of-scope auto variables;
+ * assignment of auto variables to an effective parameter of a function;
+ * out-of-bounds arrays;
+ * missing class constructors;
+ * variables not initialized by a constructor;
+ * use of memset, memcpy, etcetera on a class;
+ * non-virtual destructors for base classes;
+ * failure of the = operator to return a constant reference to itself;
+ * use of deprecated functions (mktemp, gets, scanf);
+ * exceptions thrown in destructors;
+ * memory leaks in class or function variables;
+ * C-style pointer casting within a cpp file;
+ * redundant conditions;
+ * misuse of the strtol or sprintf functions;
+ * misuse of signed char variables;
+ * unsigned division or division by zero;
+ * unused struct members;
+ * passing parameters by value;
+ * unusual pointer arithmetic (such as "abc" + 'd');
+ * dereferenced null pointers;
+ * incomplete statements;
+ * out of bounds errors in STL;
+ * misuse of iterators when iterating through a container;
+ * dereferencing of erased iterators;
+ * functions that are never called.
Source: cppcheck
Section: devel
Priority: optional
Maintainer: Reijo Tomperi <aggro80@users.sourceforge.net>
Build-Depends: debhelper (>= 7), xsltproc, docbook-xsl, docbook-xml
Standards-Version: 3.8.3
Homepage: http://cppcheck.wiki.sourceforge.net/
Package: cppcheck
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: tool for static C/C++ code analysis
This program tries to detect bugs that your C/C++ compiler doesn't see
(while your compiler can detect many problems that Cppcheck doesn't).
Cppcheck is versatile, and can check non-standard code that includes
various compiler extensions, inline assembly code, etc.
.
It includes checks for:
* pointers to out-of-scope auto variables;
* assignment of auto variables to an effective parameter of a function;
* out-of-bounds arrays;
* missing class constructors;
* variables not initialized by a constructor;
* use of memset, memcpy, etcetera on a class;
* non-virtual destructors for base classes;
* failure of the = operator to return a constant reference to itself;
* use of deprecated functions (mktemp, gets, scanf);
* exceptions thrown in destructors;
* memory leaks in class or function variables;
* C-style pointer casting within a cpp file;
* redundant conditions;
* misuse of the strtol or sprintf functions;
* misuse of signed char variables;
* unsigned division or division by zero;
* unused struct members;
* passing parameters by value;
* unusual pointer arithmetic (such as "abc" + 'd');
* dereferenced null pointers;
* incomplete statements;
* out of bounds errors in STL;
* misuse of iterators when iterating through a container;
* dereferencing of erased iterators;
* functions that are never called.
Reply to: