From aedfa47cb47c5eccc8a89956fef9fe64ea98a4f2 Mon Sep 17 00:00:00 2001 From: Arthur Baars Date: Tue, 1 Sep 2020 12:18:38 +0200 Subject: [PATCH] Add missing QHelp files --- config/identical-files.json | 45 +++++++++++++++++++ .../src/Critical/aliasAnalysisWarning.qhelp | 11 +++++ cpp/ql/src/Critical/callGraphWarning.qhelp | 12 +++++ cpp/ql/src/Critical/dataFlowWarning.qhelp | 13 ++++++ cpp/ql/src/Critical/pointsToWarning.qhelp | 11 +++++ .../src/Documentation/CommentedOutCode.qhelp | 2 +- .../Documentation/CommentedOutCodeQuery.qhelp | 25 +++++++++++ .../CommentedOutCodeMetricOverview.qhelp | 12 +++++ .../Files/CommentedOutCodeReferences.qhelp | 12 +++++ .../Metrics/Files/DuplicationProblems.qhelp | 16 +++++++ .../Files/FLinesOfDuplicatedCodeCommon.qhelp | 35 +++++++++++++++ .../src/jsf/4.05 Libraries/AV Rule 24.qhelp | 2 +- cpp/ql/src/jsf/4.10 Classes/AV Rule 85.qhelp | 2 +- .../src/jsf/4.13 Functions/AV Rule 111.qhelp | 4 +- .../src/jsf/4.13 Functions/AV Rule 114.qhelp | 2 +- .../AV Rule 135.qhelp | 2 +- .../AV Rule 140.qhelp | 2 +- cpp/ql/src/jsf/4.17 Types/AV Rule 147.qhelp | 2 +- .../jsf/4.18 Constants/AV Rule 151.1.qhelp | 2 +- .../AV Rule 154.qhelp | 2 +- .../src/jsf/4.21 Operators/AV Rule 165.qhelp | 2 +- .../AV Rule 189.qhelp | 2 +- cpp/ql/src/jsf/jsfNote.qhelp | 18 ++++++++ .../Comments/CommentedOutCode.qhelp | 2 +- .../Comments/CommentedOutCodeQuery.qhelp | 25 +++++++++++ .../CommentedOutCodeMetricOverview.qhelp | 12 +++++ .../Files/CommentedOutCodeReferences.qhelp | 12 +++++ .../Metrics/Files/DuplicationProblems.qhelp | 16 +++++++ .../CommentedOutCodeMetricOverview.qhelp | 12 +++++ .../Files/CommentedOutCodeReferences.qhelp | 12 +++++ .../Metrics/Files/FCommentRatioCommon.qhelp | 38 ++++++++++++++++ .../Metrics/Files/FLinesOfCodeOverview.qhelp | 32 +++++++++++++ .../Files/FLinesOfCodeReferences.qhelp | 10 +++++ .../Files/FLinesOfDuplicatedCodeCommon.qhelp | 35 +++++++++++++++ .../Comments/CommentedCode.qhelp | 2 +- .../Comments/CommentedOutCodeQuery.qhelp | 25 +++++++++++ .../CommentedOutCodeMetricOverview.qhelp | 12 +++++ .../src/Comments/CommentedOutCodeQuery.qhelp | 25 +++++++++++ .../Comments/CommentedOutCodeReferences.qhelp | 12 +++++ .../ql/src/Metrics/DuplicationProblems.qhelp | 16 +++++++ .../ql/src/Metrics/FCommentRatioCommon.qhelp | 38 ++++++++++++++++ .../ql/src/Metrics/FLinesOfCodeOverview.qhelp | 32 +++++++++++++ .../src/Metrics/FLinesOfCodeReferences.qhelp | 10 +++++ .../FLinesOfDuplicatedCodeCommon.qhelp | 35 +++++++++++++++ .../Metrics/FLinesOfSimilarCodeCommon.qhelp | 36 +++++++++++++++ .../CommentedOutCodeMetricOverview.qhelp | 12 +++++ .../src/Lexical/CommentedOutCodeQuery.qhelp | 25 +++++++++++ .../Lexical/CommentedOutCodeReferences.qhelp | 12 +++++ .../ql/src/Metrics/DuplicationProblems.qhelp | 1 - .../FLinesOfDuplicatedCodeCommon.qhelp | 35 +++++++++++++++ 50 files changed, 754 insertions(+), 16 deletions(-) create mode 100644 cpp/ql/src/Critical/aliasAnalysisWarning.qhelp create mode 100644 cpp/ql/src/Critical/callGraphWarning.qhelp create mode 100644 cpp/ql/src/Critical/dataFlowWarning.qhelp create mode 100644 cpp/ql/src/Critical/pointsToWarning.qhelp create mode 100644 cpp/ql/src/Documentation/CommentedOutCodeQuery.qhelp create mode 100644 cpp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp create mode 100644 cpp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp create mode 100644 cpp/ql/src/Metrics/Files/DuplicationProblems.qhelp create mode 100644 cpp/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp create mode 100644 cpp/ql/src/jsf/jsfNote.qhelp create mode 100644 csharp/ql/src/Bad Practices/Comments/CommentedOutCodeQuery.qhelp create mode 100644 csharp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp create mode 100644 csharp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp create mode 100644 csharp/ql/src/Metrics/Files/DuplicationProblems.qhelp create mode 100644 java/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp create mode 100644 java/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp create mode 100644 java/ql/src/Metrics/Files/FCommentRatioCommon.qhelp create mode 100644 java/ql/src/Metrics/Files/FLinesOfCodeOverview.qhelp create mode 100644 java/ql/src/Metrics/Files/FLinesOfCodeReferences.qhelp create mode 100644 java/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp create mode 100644 java/ql/src/Violations of Best Practice/Comments/CommentedOutCodeQuery.qhelp create mode 100644 javascript/ql/src/Comments/CommentedOutCodeMetricOverview.qhelp create mode 100644 javascript/ql/src/Comments/CommentedOutCodeQuery.qhelp create mode 100644 javascript/ql/src/Comments/CommentedOutCodeReferences.qhelp create mode 100644 javascript/ql/src/Metrics/DuplicationProblems.qhelp create mode 100644 javascript/ql/src/Metrics/FCommentRatioCommon.qhelp create mode 100644 javascript/ql/src/Metrics/FLinesOfCodeOverview.qhelp create mode 100644 javascript/ql/src/Metrics/FLinesOfCodeReferences.qhelp create mode 100644 javascript/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp create mode 100644 javascript/ql/src/Metrics/FLinesOfSimilarCodeCommon.qhelp create mode 100644 python/ql/src/Lexical/CommentedOutCodeMetricOverview.qhelp create mode 100644 python/ql/src/Lexical/CommentedOutCodeQuery.qhelp create mode 100644 python/ql/src/Lexical/CommentedOutCodeReferences.qhelp create mode 100644 python/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp diff --git a/config/identical-files.json b/config/identical-files.json index b011be4d97d..7e62497c9bf 100644 --- a/config/identical-files.json +++ b/config/identical-files.json @@ -335,5 +335,50 @@ "java/ql/src/semmle/code/xml/XML.qll", "javascript/ql/src/semmle/javascript/XML.qll", "python/ql/src/semmle/python/xml/XML.qll" + ], + "DuplicationProblems.qhelp": [ + "cpp/ql/src/Metrics/Files/DuplicationProblems.qhelp", + "csharp/ql/src/Metrics/Files/DuplicationProblems.qhelp", + "javascript/ql/src/Metrics/DuplicationProblems.qhelp", + "python/ql/src/Metrics/DuplicationProblems.qhelp" + ], + "CommentedOutCodeQuery.qhelp": [ + "cpp/ql/src/Documentation/CommentedOutCodeQuery.qhelp", + "python/ql/src/Lexical/CommentedOutCodeQuery.qhelp", + "csharp/ql/src/Bad Practices/Comments/CommentedOutCodeQuery.qhelp", + "java/ql/src/Violations of Best Practice/Comments/CommentedOutCodeQuery.qhelp", + "javascript/ql/src/Comments/CommentedOutCodeQuery.qhelp" + ], + "FLinesOfCodeReferences.qhelp": [ + "java/ql/src/Metrics/Files/FLinesOfCodeReferences.qhelp", + "javascript/ql/src/Metrics/FLinesOfCodeReferences.qhelp" + ], + "FCommentRatioCommon.qhelp": [ + "java/ql/src/Metrics/Files/FCommentRatioCommon.qhelp", + "javascript/ql/src/Metrics/FCommentRatioCommon.qhelp" + ], + "FLinesOfCodeOverview.qhelp": [ + "java/ql/src/Metrics/Files/FLinesOfCodeOverview.qhelp", + "javascript/ql/src/Metrics/FLinesOfCodeOverview.qhelp" + ], + "CommentedOutCodeMetricOverview.qhelp": [ + "cpp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp", + "csharp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp", + "java/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp", + "javascript/ql/src/Comments/CommentedOutCodeMetricOverview.qhelp", + "python/ql/src/Lexical/CommentedOutCodeMetricOverview.qhelp" + ], + "FLinesOfDuplicatedCodeCommon.qhelp": [ + "cpp/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp", + "java/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp", + "javascript/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp", + "python/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp" + ], + "CommentedOutCodeReferences.qhelp": [ + "cpp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp", + "csharp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp", + "java/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp", + "javascript/ql/src/Comments/CommentedOutCodeReferences.qhelp", + "python/ql/src/Lexical/CommentedOutCodeReferences.qhelp" ] } diff --git a/cpp/ql/src/Critical/aliasAnalysisWarning.qhelp b/cpp/ql/src/Critical/aliasAnalysisWarning.qhelp new file mode 100644 index 00000000000..77d395c7da5 --- /dev/null +++ b/cpp/ql/src/Critical/aliasAnalysisWarning.qhelp @@ -0,0 +1,11 @@ + + + + +This check is an approximation, so some results may not be actual defects in the program. +It is not possible in general to compute the exact value of the variable without running the program with all possible input data. + + + diff --git a/cpp/ql/src/Critical/callGraphWarning.qhelp b/cpp/ql/src/Critical/callGraphWarning.qhelp new file mode 100644 index 00000000000..1e408db1527 --- /dev/null +++ b/cpp/ql/src/Critical/callGraphWarning.qhelp @@ -0,0 +1,12 @@ + + + + +This check is an approximation, so some results may not be actual defects in the program. +It is not possible in general to compute which function is actually called in a virtual call, +or a call through a pointer, without running the program with all possible input data. + + + diff --git a/cpp/ql/src/Critical/dataFlowWarning.qhelp b/cpp/ql/src/Critical/dataFlowWarning.qhelp new file mode 100644 index 00000000000..f96c82226c2 --- /dev/null +++ b/cpp/ql/src/Critical/dataFlowWarning.qhelp @@ -0,0 +1,13 @@ + + + + +This check is an approximation, so some results may not be actual defects in the program. +It is not possible in general to compute the actual branch taken in conditional statements such +as "if" without running the program with all possible input data. This means that it is not possible +to determine if a particular statement is going to be executed. + + + diff --git a/cpp/ql/src/Critical/pointsToWarning.qhelp b/cpp/ql/src/Critical/pointsToWarning.qhelp new file mode 100644 index 00000000000..2fa777ebfe9 --- /dev/null +++ b/cpp/ql/src/Critical/pointsToWarning.qhelp @@ -0,0 +1,11 @@ + + + + +This check is an approximation, so some results may not be actual defects in the program. It is not possible +in general to compute the values of pointers without running the program with all input data. + + + diff --git a/cpp/ql/src/Documentation/CommentedOutCode.qhelp b/cpp/ql/src/Documentation/CommentedOutCode.qhelp index 4ce0ee029b6..ba056ab73f7 100644 --- a/cpp/ql/src/Documentation/CommentedOutCode.qhelp +++ b/cpp/ql/src/Documentation/CommentedOutCode.qhelp @@ -3,5 +3,5 @@ "qhelp.dtd"> - + diff --git a/cpp/ql/src/Documentation/CommentedOutCodeQuery.qhelp b/cpp/ql/src/Documentation/CommentedOutCodeQuery.qhelp new file mode 100644 index 00000000000..eb40ecdb708 --- /dev/null +++ b/cpp/ql/src/Documentation/CommentedOutCodeQuery.qhelp @@ -0,0 +1,25 @@ + + + + +

+Commented-out code is distracting and confusing for developers who read the surrounding code, +and its significance is often unclear. It will not get compiled or tested when the code around +it changes, so it's likely to break over time. For these reasons, commented-out code should be +avoided. +

+ + + + + +

+Remove or reinstate the commented-out code. If you want to include a snippet of example code +in a comment, consider enclosing it in quotes or marking it up as appropriate for the source +language. +

+ + + diff --git a/cpp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp b/cpp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp new file mode 100644 index 00000000000..217b6d17529 --- /dev/null +++ b/cpp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp @@ -0,0 +1,12 @@ + + + +

+This metric counts the number of lines of commented-out code in each file. Large amounts of +commented-out code often indicate poorly maintained code. +

+ + + diff --git a/cpp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp b/cpp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp new file mode 100644 index 00000000000..462eb7795f9 --- /dev/null +++ b/cpp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp @@ -0,0 +1,12 @@ + + + + +
  • Mark Needham: The danger of commenting out code.
    • +
  • Los Techies: Commented Code == Technical Debt.
    • +
  • High Integrity C++ Coding Standard: 2.3.2 Do not comment out code.
    • + +     +     diff --git a/cpp/ql/src/Metrics/Files/DuplicationProblems.qhelp b/cpp/ql/src/Metrics/Files/DuplicationProblems.qhelp new file mode 100644 index 00000000000..54397da6c99 --- /dev/null +++ b/cpp/ql/src/Metrics/Files/DuplicationProblems.qhelp @@ -0,0 +1,16 @@ + + + +

    +Duplicated code increases overall code size, making the code base +harder to maintain and harder to understand. It also becomes harder to fix bugs, +since a programmer applying a fix to one copy has to always remember to update +other copies accordingly. Finally, code duplication is generally an indication of +a poorly designed or hastily written code base, which typically suffers from other +problems as well. +

    + +     +     diff --git a/cpp/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp b/cpp/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp new file mode 100644 index 00000000000..17171fb7587 --- /dev/null +++ b/cpp/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp @@ -0,0 +1,35 @@ + + + + +

    +This metric measures the number of lines in a file that are contained within a block that is duplicated elsewhere. These lines may include code, comments and whitespace, and the duplicate block may be in this file or in another file. +

    + +

    +A file that contains many lines that are duplicated within the code base is problematic +for a number of reasons. +

    + +     + + + + +

    +Refactor files with lots of duplicated code to extract the common code into +a shared library or module. +

    + +     + + + +
  • Wikipedia: Duplicate code.
    • +
  • M. Fowler, Refactoring. Addison-Wesley, 1999.
    • + + +     +     diff --git a/cpp/ql/src/jsf/4.05 Libraries/AV Rule 24.qhelp b/cpp/ql/src/jsf/4.05 Libraries/AV Rule 24.qhelp index 7513d84d526..70c8460c835 100644 --- a/cpp/ql/src/jsf/4.05 Libraries/AV Rule 24.qhelp +++ b/cpp/ql/src/jsf/4.05 Libraries/AV Rule 24.qhelp @@ -7,7 +7,7 @@ - +

    This query highlights calls to the standard library functions abort, exit, getenv and system. diff --git a/cpp/ql/src/jsf/4.10 Classes/AV Rule 85.qhelp b/cpp/ql/src/jsf/4.10 Classes/AV Rule 85.qhelp index 61275fedefa..69cc5322ad5 100644 --- a/cpp/ql/src/jsf/4.10 Classes/AV Rule 85.qhelp +++ b/cpp/ql/src/jsf/4.10 Classes/AV Rule 85.qhelp @@ -7,7 +7,7 @@ - +

    This query ensures that all operators with opposites (e.g. == and !=) are both defined, and diff --git a/cpp/ql/src/jsf/4.13 Functions/AV Rule 111.qhelp b/cpp/ql/src/jsf/4.13 Functions/AV Rule 111.qhelp index 7dbbb12dba3..614fe4711fd 100644 --- a/cpp/ql/src/jsf/4.13 Functions/AV Rule 111.qhelp +++ b/cpp/ql/src/jsf/4.13 Functions/AV Rule 111.qhelp @@ -7,7 +7,7 @@ - +

    This query highlights return statements that return pointers to an object allocated on the stack. The lifetime @@ -18,7 +18,7 @@ memory after the function has already returned will have undefined results. - + diff --git a/cpp/ql/src/jsf/4.13 Functions/AV Rule 114.qhelp b/cpp/ql/src/jsf/4.13 Functions/AV Rule 114.qhelp index e47368f5d66..086d1ea1fb6 100644 --- a/cpp/ql/src/jsf/4.13 Functions/AV Rule 114.qhelp +++ b/cpp/ql/src/jsf/4.13 Functions/AV Rule 114.qhelp @@ -12,7 +12,7 @@ calling convention for x86, it would be whatever value was in the AX/EAX registe assuming the function had a non-float return type that can fit in a machine word.

    - + diff --git a/cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 135.qhelp b/cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 135.qhelp index 6729583ff77..d67d84c5e06 100644 --- a/cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 135.qhelp +++ b/cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 135.qhelp @@ -7,7 +7,7 @@ - +

    This query highlights identifiers in an inner scope that hide (have the same name as) an identifier in an outer scope. diff --git a/cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 140.qhelp b/cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 140.qhelp index e184b9edd6f..73e66f0b006 100644 --- a/cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 140.qhelp +++ b/cpp/ql/src/jsf/4.15 Declarations and Definitions/AV Rule 140.qhelp @@ -7,7 +7,7 @@ - +

    This query highlights variables with the register storage class specifier. Modern compilers are now capable of diff --git a/cpp/ql/src/jsf/4.17 Types/AV Rule 147.qhelp b/cpp/ql/src/jsf/4.17 Types/AV Rule 147.qhelp index 75c4f03e980..1633cb2a867 100644 --- a/cpp/ql/src/jsf/4.17 Types/AV Rule 147.qhelp +++ b/cpp/ql/src/jsf/4.17 Types/AV Rule 147.qhelp @@ -7,7 +7,7 @@ - +

    This query highlights portions of code that can expose the floating point implementation of the underlying diff --git a/cpp/ql/src/jsf/4.18 Constants/AV Rule 151.1.qhelp b/cpp/ql/src/jsf/4.18 Constants/AV Rule 151.1.qhelp index 9c6c369cfed..b30e828428c 100644 --- a/cpp/ql/src/jsf/4.18 Constants/AV Rule 151.1.qhelp +++ b/cpp/ql/src/jsf/4.18 Constants/AV Rule 151.1.qhelp @@ -7,7 +7,7 @@ - +

    This query highlights string literals that are assigned to a non-const variable. String literals diff --git a/cpp/ql/src/jsf/4.20 Unions and Bit Fields/AV Rule 154.qhelp b/cpp/ql/src/jsf/4.20 Unions and Bit Fields/AV Rule 154.qhelp index 3c502a24928..946e0873ab0 100644 --- a/cpp/ql/src/jsf/4.20 Unions and Bit Fields/AV Rule 154.qhelp +++ b/cpp/ql/src/jsf/4.20 Unions and Bit Fields/AV Rule 154.qhelp @@ -7,7 +7,7 @@ - +

    This query finds bit fields with members that are not explicitly declared to be unsigned. diff --git a/cpp/ql/src/jsf/4.21 Operators/AV Rule 165.qhelp b/cpp/ql/src/jsf/4.21 Operators/AV Rule 165.qhelp index 5961991fcdc..1beb8b94f35 100644 --- a/cpp/ql/src/jsf/4.21 Operators/AV Rule 165.qhelp +++ b/cpp/ql/src/jsf/4.21 Operators/AV Rule 165.qhelp @@ -7,7 +7,7 @@ - +

    This query finds unsigned values that are being negated. Behavior is undefined in such cases. diff --git a/cpp/ql/src/jsf/4.24 Control Flow Structures/AV Rule 189.qhelp b/cpp/ql/src/jsf/4.24 Control Flow Structures/AV Rule 189.qhelp index e65f5b8dfb4..85db1463d56 100644 --- a/cpp/ql/src/jsf/4.24 Control Flow Structures/AV Rule 189.qhelp +++ b/cpp/ql/src/jsf/4.24 Control Flow Structures/AV Rule 189.qhelp @@ -6,7 +6,7 @@ - +

    Use of goto statements makes code more difficult to understand and maintain. Consequently, the use of goto statements is deprecated except as a mechanism for breaking out of multiple nested loops. diff --git a/cpp/ql/src/jsf/jsfNote.qhelp b/cpp/ql/src/jsf/jsfNote.qhelp new file mode 100644 index 00000000000..4a05d0c6e34 --- /dev/null +++ b/cpp/ql/src/jsf/jsfNote.qhelp @@ -0,0 +1,18 @@ + + + +

    +This query is part of a suite that tests code against +the Joint Strike Fighter Air Vehicle C++ Coding Standard (JSF). +Alerts reported by this query highlight code that may break the +JSF rule listed in the References section. +

    + +

    +The JSF rule this query tests is likely to be too strict for projects +that do not follow the JSF standard. +

    + + diff --git a/csharp/ql/src/Bad Practices/Comments/CommentedOutCode.qhelp b/csharp/ql/src/Bad Practices/Comments/CommentedOutCode.qhelp index 4ce0ee029b6..0997169f4df 100644 --- a/csharp/ql/src/Bad Practices/Comments/CommentedOutCode.qhelp +++ b/csharp/ql/src/Bad Practices/Comments/CommentedOutCode.qhelp @@ -3,5 +3,5 @@ "qhelp.dtd"> - + diff --git a/csharp/ql/src/Bad Practices/Comments/CommentedOutCodeQuery.qhelp b/csharp/ql/src/Bad Practices/Comments/CommentedOutCodeQuery.qhelp new file mode 100644 index 00000000000..eb40ecdb708 --- /dev/null +++ b/csharp/ql/src/Bad Practices/Comments/CommentedOutCodeQuery.qhelp @@ -0,0 +1,25 @@ + + + + +

    +Commented-out code is distracting and confusing for developers who read the surrounding code, +and its significance is often unclear. It will not get compiled or tested when the code around +it changes, so it's likely to break over time. For these reasons, commented-out code should be +avoided. +

    + +     + + + +

    +Remove or reinstate the commented-out code. If you want to include a snippet of example code +in a comment, consider enclosing it in quotes or marking it up as appropriate for the source +language. +

    + +     +     diff --git a/csharp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp b/csharp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp new file mode 100644 index 00000000000..217b6d17529 --- /dev/null +++ b/csharp/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp @@ -0,0 +1,12 @@ + + + +

    +This metric counts the number of lines of commented-out code in each file. Large amounts of +commented-out code often indicate poorly maintained code. +

    + +     +     diff --git a/csharp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp b/csharp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp new file mode 100644 index 00000000000..462eb7795f9 --- /dev/null +++ b/csharp/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp @@ -0,0 +1,12 @@ + + + + +
  • Mark Needham: The danger of commenting out code.
    • +
  • Los Techies: Commented Code == Technical Debt.
    • +
  • High Integrity C++ Coding Standard: 2.3.2 Do not comment out code.
    • + +     +     diff --git a/csharp/ql/src/Metrics/Files/DuplicationProblems.qhelp b/csharp/ql/src/Metrics/Files/DuplicationProblems.qhelp new file mode 100644 index 00000000000..54397da6c99 --- /dev/null +++ b/csharp/ql/src/Metrics/Files/DuplicationProblems.qhelp @@ -0,0 +1,16 @@ + + + +

    +Duplicated code increases overall code size, making the code base +harder to maintain and harder to understand. It also becomes harder to fix bugs, +since a programmer applying a fix to one copy has to always remember to update +other copies accordingly. Finally, code duplication is generally an indication of +a poorly designed or hastily written code base, which typically suffers from other +problems as well. +

    + +     +     diff --git a/java/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp b/java/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp new file mode 100644 index 00000000000..217b6d17529 --- /dev/null +++ b/java/ql/src/Metrics/Files/CommentedOutCodeMetricOverview.qhelp @@ -0,0 +1,12 @@ + + + +

    +This metric counts the number of lines of commented-out code in each file. Large amounts of +commented-out code often indicate poorly maintained code. +

    + +     +     diff --git a/java/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp b/java/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp new file mode 100644 index 00000000000..462eb7795f9 --- /dev/null +++ b/java/ql/src/Metrics/Files/CommentedOutCodeReferences.qhelp @@ -0,0 +1,12 @@ + + + + +
  • Mark Needham: The danger of commenting out code.
    • +
  • Los Techies: Commented Code == Technical Debt.
    • +
  • High Integrity C++ Coding Standard: 2.3.2 Do not comment out code.
    • + +     +     diff --git a/java/ql/src/Metrics/Files/FCommentRatioCommon.qhelp b/java/ql/src/Metrics/Files/FCommentRatioCommon.qhelp new file mode 100644 index 00000000000..8e22cabef7e --- /dev/null +++ b/java/ql/src/Metrics/Files/FCommentRatioCommon.qhelp @@ -0,0 +1,38 @@ + + + +

    +This metric measures the percentage of a file's lines that are comment rather +than code. +

    + +

    +A low percentage of comments in a file may indicate either a potentially +worrying lack of documentation or that the file was generated by an automated +tool. A quick visual inspection should be sufficient to distinguish between +the two cases. +

    + +     + + +

    +Files that were not auto-generated and have a low comment percentage should +be documented more fully. Refer to [McConnell] for more on how to write good +comments. +

    + + +     + + + +
  • +S. McConnell. Code Complete, 2nd Edition. Microsoft Press, 2004. +
    • + + +     +     diff --git a/java/ql/src/Metrics/Files/FLinesOfCodeOverview.qhelp b/java/ql/src/Metrics/Files/FLinesOfCodeOverview.qhelp new file mode 100644 index 00000000000..c19fc74cf20 --- /dev/null +++ b/java/ql/src/Metrics/Files/FLinesOfCodeOverview.qhelp @@ -0,0 +1,32 @@ + + + +

    +There are a number of problems associated with a high number of lines of code: +

    + +
      +
    • +It can be difficult to understand and maintain, even with good tool support. +
      • + +
    • +It increases the likelihood of multiple developers needing to work on the same +file at once, and it therefore increases the likelihood of merge conflicts. +
      • + +
    • +It may increase network traffic if you use a version control system that requires the whole file to +be transmitted even for a tiny change. +
      • + +
    • +It may arise as a result of bundling many unrelated things into the +same file, and so it can indicate weak code organization. +
      • +
    + +     +     diff --git a/java/ql/src/Metrics/Files/FLinesOfCodeReferences.qhelp b/java/ql/src/Metrics/Files/FLinesOfCodeReferences.qhelp new file mode 100644 index 00000000000..2a86d9a8c2b --- /dev/null +++ b/java/ql/src/Metrics/Files/FLinesOfCodeReferences.qhelp @@ -0,0 +1,10 @@ + + + +
  • + M. Fowler, Refactoring. Addison-Wesley, 1999. +
    • +     +     \ No newline at end of file diff --git a/java/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp b/java/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp new file mode 100644 index 00000000000..17171fb7587 --- /dev/null +++ b/java/ql/src/Metrics/Files/FLinesOfDuplicatedCodeCommon.qhelp @@ -0,0 +1,35 @@ + + + + +

    +This metric measures the number of lines in a file that are contained within a block that is duplicated elsewhere. These lines may include code, comments and whitespace, and the duplicate block may be in this file or in another file. +

    + +

    +A file that contains many lines that are duplicated within the code base is problematic +for a number of reasons. +

    + +     + + + + +

    +Refactor files with lots of duplicated code to extract the common code into +a shared library or module. +

    + +     + + + +
  • Wikipedia: Duplicate code.
    • +
  • M. Fowler, Refactoring. Addison-Wesley, 1999.
    • + + +     +     diff --git a/java/ql/src/Violations of Best Practice/Comments/CommentedCode.qhelp b/java/ql/src/Violations of Best Practice/Comments/CommentedCode.qhelp index 4ce0ee029b6..0997169f4df 100644 --- a/java/ql/src/Violations of Best Practice/Comments/CommentedCode.qhelp +++ b/java/ql/src/Violations of Best Practice/Comments/CommentedCode.qhelp @@ -3,5 +3,5 @@ "qhelp.dtd"> - + diff --git a/java/ql/src/Violations of Best Practice/Comments/CommentedOutCodeQuery.qhelp b/java/ql/src/Violations of Best Practice/Comments/CommentedOutCodeQuery.qhelp new file mode 100644 index 00000000000..eb40ecdb708 --- /dev/null +++ b/java/ql/src/Violations of Best Practice/Comments/CommentedOutCodeQuery.qhelp @@ -0,0 +1,25 @@ + + + + +

    +Commented-out code is distracting and confusing for developers who read the surrounding code, +and its significance is often unclear. It will not get compiled or tested when the code around +it changes, so it's likely to break over time. For these reasons, commented-out code should be +avoided. +

    + +     + + + +

    +Remove or reinstate the commented-out code. If you want to include a snippet of example code +in a comment, consider enclosing it in quotes or marking it up as appropriate for the source +language. +

    + +     +     diff --git a/javascript/ql/src/Comments/CommentedOutCodeMetricOverview.qhelp b/javascript/ql/src/Comments/CommentedOutCodeMetricOverview.qhelp new file mode 100644 index 00000000000..217b6d17529 --- /dev/null +++ b/javascript/ql/src/Comments/CommentedOutCodeMetricOverview.qhelp @@ -0,0 +1,12 @@ + + + +

    +This metric counts the number of lines of commented-out code in each file. Large amounts of +commented-out code often indicate poorly maintained code. +

    + +     +     diff --git a/javascript/ql/src/Comments/CommentedOutCodeQuery.qhelp b/javascript/ql/src/Comments/CommentedOutCodeQuery.qhelp new file mode 100644 index 00000000000..eb40ecdb708 --- /dev/null +++ b/javascript/ql/src/Comments/CommentedOutCodeQuery.qhelp @@ -0,0 +1,25 @@ + + + + +

    +Commented-out code is distracting and confusing for developers who read the surrounding code, +and its significance is often unclear. It will not get compiled or tested when the code around +it changes, so it's likely to break over time. For these reasons, commented-out code should be +avoided. +

    + +     + + + +

    +Remove or reinstate the commented-out code. If you want to include a snippet of example code +in a comment, consider enclosing it in quotes or marking it up as appropriate for the source +language. +

    + +     +     diff --git a/javascript/ql/src/Comments/CommentedOutCodeReferences.qhelp b/javascript/ql/src/Comments/CommentedOutCodeReferences.qhelp new file mode 100644 index 00000000000..462eb7795f9 --- /dev/null +++ b/javascript/ql/src/Comments/CommentedOutCodeReferences.qhelp @@ -0,0 +1,12 @@ + + + + +
  • Mark Needham: The danger of commenting out code.
    • +
  • Los Techies: Commented Code == Technical Debt.
    • +
  • High Integrity C++ Coding Standard: 2.3.2 Do not comment out code.
    • + +     +     diff --git a/javascript/ql/src/Metrics/DuplicationProblems.qhelp b/javascript/ql/src/Metrics/DuplicationProblems.qhelp new file mode 100644 index 00000000000..54397da6c99 --- /dev/null +++ b/javascript/ql/src/Metrics/DuplicationProblems.qhelp @@ -0,0 +1,16 @@ + + + +

    +Duplicated code increases overall code size, making the code base +harder to maintain and harder to understand. It also becomes harder to fix bugs, +since a programmer applying a fix to one copy has to always remember to update +other copies accordingly. Finally, code duplication is generally an indication of +a poorly designed or hastily written code base, which typically suffers from other +problems as well. +

    + +     +     diff --git a/javascript/ql/src/Metrics/FCommentRatioCommon.qhelp b/javascript/ql/src/Metrics/FCommentRatioCommon.qhelp new file mode 100644 index 00000000000..8e22cabef7e --- /dev/null +++ b/javascript/ql/src/Metrics/FCommentRatioCommon.qhelp @@ -0,0 +1,38 @@ + + + +

    +This metric measures the percentage of a file's lines that are comment rather +than code. +

    + +

    +A low percentage of comments in a file may indicate either a potentially +worrying lack of documentation or that the file was generated by an automated +tool. A quick visual inspection should be sufficient to distinguish between +the two cases. +

    + +     + + +

    +Files that were not auto-generated and have a low comment percentage should +be documented more fully. Refer to [McConnell] for more on how to write good +comments. +

    + + +     + + + +
  • +S. McConnell. Code Complete, 2nd Edition. Microsoft Press, 2004. +
    • + + +     +     diff --git a/javascript/ql/src/Metrics/FLinesOfCodeOverview.qhelp b/javascript/ql/src/Metrics/FLinesOfCodeOverview.qhelp new file mode 100644 index 00000000000..c19fc74cf20 --- /dev/null +++ b/javascript/ql/src/Metrics/FLinesOfCodeOverview.qhelp @@ -0,0 +1,32 @@ + + + +

    +There are a number of problems associated with a high number of lines of code: +

    + +
      +
    • +It can be difficult to understand and maintain, even with good tool support. +
      • + +
    • +It increases the likelihood of multiple developers needing to work on the same +file at once, and it therefore increases the likelihood of merge conflicts. +
      • + +
    • +It may increase network traffic if you use a version control system that requires the whole file to +be transmitted even for a tiny change. +
      • + +
    • +It may arise as a result of bundling many unrelated things into the +same file, and so it can indicate weak code organization. +
      • +
    + +     +     diff --git a/javascript/ql/src/Metrics/FLinesOfCodeReferences.qhelp b/javascript/ql/src/Metrics/FLinesOfCodeReferences.qhelp new file mode 100644 index 00000000000..2a86d9a8c2b --- /dev/null +++ b/javascript/ql/src/Metrics/FLinesOfCodeReferences.qhelp @@ -0,0 +1,10 @@ + + + +
  • + M. Fowler, Refactoring. Addison-Wesley, 1999. +
    • +     +     \ No newline at end of file diff --git a/javascript/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp b/javascript/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp new file mode 100644 index 00000000000..17171fb7587 --- /dev/null +++ b/javascript/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp @@ -0,0 +1,35 @@ + + + + +

    +This metric measures the number of lines in a file that are contained within a block that is duplicated elsewhere. These lines may include code, comments and whitespace, and the duplicate block may be in this file or in another file. +

    + +

    +A file that contains many lines that are duplicated within the code base is problematic +for a number of reasons. +

    + +     + + + + +

    +Refactor files with lots of duplicated code to extract the common code into +a shared library or module. +

    + +     + + + +
  • Wikipedia: Duplicate code.
    • +
  • M. Fowler, Refactoring. Addison-Wesley, 1999.
    • + + +     +     diff --git a/javascript/ql/src/Metrics/FLinesOfSimilarCodeCommon.qhelp b/javascript/ql/src/Metrics/FLinesOfSimilarCodeCommon.qhelp new file mode 100644 index 00000000000..86388e18f16 --- /dev/null +++ b/javascript/ql/src/Metrics/FLinesOfSimilarCodeCommon.qhelp @@ -0,0 +1,36 @@ + + + + +

    +This metric measures the number of lines in a file that are contained within a block that is duplicated elsewhere. These lines may include code, comments and whitespace, and the duplicate block may be in this file or in another file. +

    + +

    +A file that contains many lines that are similar to other code within the code base is +problematic for the same reasons as a file that contains a lot of (exactly) +duplicated code. +

    + +     + + + + +

    +Refactor similar code snippets by extracting common functionality into functions +that can be reused across modules. +

    + +     + + + +
  • Wikipedia: Duplicate code.
    • +
  • M. Fowler, Refactoring. Addison-Wesley, 1999.
    • + + +     +     diff --git a/python/ql/src/Lexical/CommentedOutCodeMetricOverview.qhelp b/python/ql/src/Lexical/CommentedOutCodeMetricOverview.qhelp new file mode 100644 index 00000000000..217b6d17529 --- /dev/null +++ b/python/ql/src/Lexical/CommentedOutCodeMetricOverview.qhelp @@ -0,0 +1,12 @@ + + + +

    +This metric counts the number of lines of commented-out code in each file. Large amounts of +commented-out code often indicate poorly maintained code. +

    + +     +     diff --git a/python/ql/src/Lexical/CommentedOutCodeQuery.qhelp b/python/ql/src/Lexical/CommentedOutCodeQuery.qhelp new file mode 100644 index 00000000000..eb40ecdb708 --- /dev/null +++ b/python/ql/src/Lexical/CommentedOutCodeQuery.qhelp @@ -0,0 +1,25 @@ + + + + +

    +Commented-out code is distracting and confusing for developers who read the surrounding code, +and its significance is often unclear. It will not get compiled or tested when the code around +it changes, so it's likely to break over time. For these reasons, commented-out code should be +avoided. +

    + +     + + + +

    +Remove or reinstate the commented-out code. If you want to include a snippet of example code +in a comment, consider enclosing it in quotes or marking it up as appropriate for the source +language. +

    + +     +     diff --git a/python/ql/src/Lexical/CommentedOutCodeReferences.qhelp b/python/ql/src/Lexical/CommentedOutCodeReferences.qhelp new file mode 100644 index 00000000000..462eb7795f9 --- /dev/null +++ b/python/ql/src/Lexical/CommentedOutCodeReferences.qhelp @@ -0,0 +1,12 @@ + + + + +
  • Mark Needham: The danger of commenting out code.
    • +
  • Los Techies: Commented Code == Technical Debt.
    • +
  • High Integrity C++ Coding Standard: 2.3.2 Do not comment out code.
    • + +     +     diff --git a/python/ql/src/Metrics/DuplicationProblems.qhelp b/python/ql/src/Metrics/DuplicationProblems.qhelp index e55f8f8e455..54397da6c99 100644 --- a/python/ql/src/Metrics/DuplicationProblems.qhelp +++ b/python/ql/src/Metrics/DuplicationProblems.qhelp @@ -12,6 +12,5 @@ a poorly designed or hastily written code base, which typically suffers from oth problems as well.

    -     diff --git a/python/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp b/python/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp new file mode 100644 index 00000000000..17171fb7587 --- /dev/null +++ b/python/ql/src/Metrics/FLinesOfDuplicatedCodeCommon.qhelp @@ -0,0 +1,35 @@ + + + + +

    +This metric measures the number of lines in a file that are contained within a block that is duplicated elsewhere. These lines may include code, comments and whitespace, and the duplicate block may be in this file or in another file. +

    + +

    +A file that contains many lines that are duplicated within the code base is problematic +for a number of reasons. +

    + +     + + + + +

    +Refactor files with lots of duplicated code to extract the common code into +a shared library or module. +

    + +     + + + +
  • Wikipedia: Duplicate code.
    • +
  • M. Fowler, Refactoring. Addison-Wesley, 1999.
    • + + +     +