EN JP CN

レポートされたメトリックのしきい値の変更

レポートされたメトリックのしきい値の変更

レポートされたメトリックのしきい値の変更

レポートされたメトリックのしきい値の変更

Klocwork は、組織の基準と優先度に基づいて設定されたメトリックしきい値違反を検出して報告することができます。デフォルトのメトリックしきい値構成ファイルは、いくつかの基本メトリックをカバーするレポートを生成します。ただし、この構成ファイルを変更することで、コード品質目標との関連性が高いエラーを Klocwork に報告させることができます。

デフォルトのメトリックしきい値構成ファイルについて

メトリックしきい値構成ファイルは、Klocwork に報告させるしきい値を設定するテキストファイルです。メトリックしきい値違反があると、Klocwork はその違反を報告します。構成ファイルの各行が、1 つのしきい値を設定します。

設定できるメトリックしきい値のタイプをいくつか示します。

  • 1 ファイルのコードの行数は、5,000 以下である必要があります。
  • ファイルの複雑度 <=20。
    • ファイルで定義できるクラス数は 1 までです。
    サポート対象メトリクスをすべて記載したリストについては、メトリックリファレンスを参照してください。
    注: Klocworkがメトリックしきい値違反を報告する場合、エラーコード内の非 ASCII 文字は "_" (アンダースコア) で置換されます。ただし、その場合も (UTF-8 エンコードのファイルでは) カテゴリ名とメッセージに非 ASCII 文字が表示されます 。詳細については、Klocwork は非ASCII エンコードをサポートしているを参照してください。メトリックしきい値構成ファイルは、metrics_default.mconf と呼ばれ、次のいずれかの場所にあります。
  • デフォルトの場所である <Klocwork_install>/config
    または
  • <projects_directory>/config (非デフォルトの場所にある projects_root ディレクトリを持つ統合プロジェクトの場合)
注: このデフォルトファイルでは、メトリック規則はすべてコメントアウトされます。メトリックしきい値違反について報告するため、メトリック規則に関するコメントはしないものとします。

metrics_default.mconf ファイルに、作成できるしきい値違反規則のタイプがいくつか示されています。

メトリックしきい値構成ファイルの編集

  1. 設定するメトリックしきい値を特定します。
  2. 構成ファイルがあるディレクトリに移動し、 metrics_default.mconfファイルをコピーして、任意の名前で保存します。 または、任意の名前と場所を使用してメトリックしきい値構成ファイルを新規作成します。ファイル拡張子は .mconf である必要があります。
    注: 既存の構成ファイルを変更する場合は、事前にバックアップコピーを作成してください。
  3. 新規または変更したデフォルトのメトリックしきい値構成ファイルで、必要に応じて内容を変更します。使用する構文の概要については、次のセクションおよびメトリックしきい値規則のカテゴリの作成に説明してあります。
  4. ファイルを保存します。

メトリックしきい値規則の構文

メトリックしきい値構成ファイルの各行は、Klocwork に違反を検出させるメトリックしきい値 1 件を表します。ファイルの各メトリックしきい値規則には、次のフィールドがあります。

Name;Entity-type;Metric-expression;Error-threshold;Warning-threshold

以降のセクションで、各フィールドについて詳細に説明していきます。

構成ファイル構文で、コメントと空白行を使用することができます。コメント行の先頭にポンド記号 (#) を使用すると、その行は規則と見なされなくなります。

ヒント: #!alias 構文で、規則内のテキストを代わりに使用することができます。

#!alias MetricCode = <expression>

このコメント以降は、"MetricCode" の出現箇所のテキストはすべて <expression> に代えられます。

名前

[Name] は、検出されたときにレポートに記載される違反に関する簡単な説明です。たとえば、クラス宣言数などです。完全なリストについては、メトリックリファレンスにある一覧表の [名前] 列を参照してください。名前は、すべての .mconf ファイルで使用されているメトリック規則名の間で一意でなければなりません。

Entity-type

Entity-type は、メトリックしきい値が該当するソフトウェアエンティティです。同じしきい値を複数のソフトウェアエンティティに適用する場合、1 つのカンマ区切りリストに複数個指定することができます。たとえば、次のようになります。

Number of paths (NP);FUNCTION,METHOD;NOINDPATHS;10;7

以降の表に、各メトリックカテゴリで使用できるエンティティタイプを示します。

各メトリックカテゴリに該当するエンティティタイプ:C/C++

メトリックカテゴリ 該当するエンティティタイプ
ファイルレベルメトリックFILE
クラスレベルメトリックCLASS、TYPE、CLASS-TEMPLATE
関数レベルおよびメソッドレベルメトリックFUNCTION、CLASS-METHOD、FUNCTION-TEMPLATE、TEMPLATE-MEMBER

クラスレベルしきい値規則の TYPE は、構造と和集合を表します。

関数レベルのメトリックしきい値ルールの TEMPLATE-MEMBER は、クラステンプレートメソッドを表します。

各メトリックカテゴリに該当するエンティティタイプ:Java

メトリックカテゴリ 該当するエンティティタイプ
ファイルレベルメトリックFILE
クラスレベルメトリッククラス
関数レベルおよびメソッドレベルメトリックCLASS-METHOD

Metric-expression

Metric-expression は、次のうちのいずれかです。

  • メトリックリファレンスにあるファイルレベルメトリック表の ["メトリックコード"] 列にある LOC_FILE (1 ファイルあたりのコード行数) などの簡単なメトリックコード。
  • 論理演算または算術演算および関数呼び出しを含む複雑な式 (下の '関数呼び出し値' (例:log(LOC/NOROUTINES)) を参照)。

Error-threshold

Error-threshold は、メトリックのしきい値を表す数です。詳細については、(下の) 数値を参照してください。<、<=、または >= などの論理演算を接頭辞として付けることができます。詳細については、下の論理演算を参照してください。このフィールドに数だけを入力した場合、適用されるデフォルト演算は、"大なり" (>) です。このメトリックの違反は、エラーとして報告されます。たとえば、1 ファイルメトリックあたりのコード行数のエラーしきい値を <100 に設定した場合、1 ファイル内のコード行数 (LOC_FILE) が 100 未満だと、エラーが報告されます。

ヒント: 警告だけ報告しエラー報告は不要のメトリックしきい値がある場合もあります。これを行うには、エラーしきい値を決して真にならない条件に設定します。たとえば、コード行数が 100 未満のファイルで警告を報告させるには、エラーしきい値を <0 (決して真にならない条件)、警告しきい値を <100 に設定します。

Warning-threshold

Warning-threshold は、式で定義されたメトリックのしきい値を表す数です。この数には、<、<=、または >= などの論理演算を接頭辞として付けることができます。このフィールドに数だけを入力した場合、適用されるデフォルト演算は、"大なり" (>) です。このメトリックの違反は、警告として報告されます。たとえば、1 ファイルメトリックあたりのコード行数の警告しきい値を <100 に設定した場合、1 ファイル内のコード行数 (LOC_FILE) が 100 未満だと、警告が報告されます。

メトリックが警告とエラーの両方のしきい値を超えた場合は、エラーメッセージのみが報告されます。

フルメトリックしきい値規則の例

Percent of comments;FILE;LINESCOMM/LOC_FILE*100;<5;<10

関数呼び出し値

[FunctionCall] には、次の関数を指定することができます。

abs(X)引数の絶対値を返します。
atan2(X,Y)範囲 -pi ~ pi における Y/X の逆正接を返します。
cos(X)X (弧度で表現) の余弦を返します。
exp(X)e (自然対数底) の X 乗を返します。
int(X)X の整数部を返します。
log(X)X の 自然対数 (底 e) を返します。
sin(X)X (弧度で表現) の正弦を返します。
sqrt(X)X の平方根を返します。

数値

[Number] は次のいずれかになります。

  • 整数は、実数の自然数と定義されます。たとえば、1231000 です。
  • 小数は、中に小数点を含む数と定義されます。たとえば、123.45.6. です。
  • 浮動小数点科学的記数法は、1 ~ 10 の数に 10 の何乗かをかけた数と定義されます。たとえば、2.3E-103E-5 です。

論理演算

[Logical operations] は、次のうちのいずれかです。

<小なり
<=以下
 等しい
>大なり ([しきい値] フィールドに数だけ指定された場合のデフォルト)
>=以上
!=等しくない

メトリックしきい値規則のカテゴリの作成

必要に応じて、複数のメトリックしきい値規則をカテゴリにまとめて、有意義なカテゴリ名を付けることができます。

カテゴリ名は自由に付けることができます。ただし、1 つのカテゴリにまとめられたすべてのメトリックには、同じエラーまたは警告重要度レベルが割り当てられるため、検出された違反への対応の重要性が等しくなることに注意してください。

構成ファイルでのカテゴリの指定

カテゴリは、次のような行で構成ファイルで指定します。

WARNING.SEVERITY=7 ERROR.SEVERITY=3 WARNING.CATEGORY="ユーザー定義警告カテゴリ 1" ERROR.CATEGORY="ユーザー定義エラーカテゴリ 1"

フィールド

  • WARNING.SEVERITY= 違反の重大度を表す数値の前に置かれます。 1 が最も重大、10 が最低です。規則の [警告] フィールドの値を超えた場合、このカテゴリの規則の違反は、警告として表示されます。
  • ERROR.SEVERITY=違反の重大度を表す数値の前に置かれます。 1 が最も重大、10 が最低です。規則の [エラー] フィールドの値を超えた場合、このカテゴリの規則の違反は、エラーとして表示されます。
  • WARNING.CATEGORY= 規則のカテゴリ名の前に置かれます。名前は次のように引用符で囲む必要があります。"カテゴリ名"
  • ERROR.CATEGORY=規則のカテゴリ名の前に置かれます。名前は次のように引用符で囲む必要があります。"カテゴリ名"

デフォルト構成ファイルには、3 つのプレースホルダー "ユーザー定義警告カテゴリ" が含まれています。

メトリックしきい値の設定例

次のテーブルでは、Klocwork レポートに含める典型的なメトリックしきい値について説明し、構文を示します。[名前] フィールド (メトリックしきい値の説明欄) のテキストを変更できることを忘れないでください。

例 1

規則の意図:ファイルレベルで、コメント行のパーセントを示します。コメント行が全行数の 5% 未満の場合、エラーが発行されます。コメント行が全行数の 5% 超 10% 未満の場合、警告が発行されます。

規則構文:Name;Kind;Expression;Error threshold;Warning threshold

Percent of comments;FILE;LINESCOMM/LOC_FILE*100;<5;<10

例 2

規則の意図:固有の関数への呼び出しの数を示します。呼び出しが 20 以上の場合、エラーが発行されます。15 ~ 19 の場合、警告が発行されます。

規則構文:Name;Kind;Expression;Error threshold;Warning threshold

Number of unique calls (UCT);FUNCTION,CLASS-METHOD;NOCALLS;20;15

例 3

つの段階を以下の例に示します。ソースコードファイルは、何から始めるのかを示します。

1  /* function main */
2  main(){
3    printf("Hello world\n");
4  }
5 
6  hello(){
7    // tbd
8  }
9  test(int a){
10   return 1;
11 }
12

メトリックしきい値構成ファイルのしきい値を変更します。

Number of lines of code of function;FUNCTION;LOC_FILE;>100;>30 Cyclomatic complexity (VG);FUNCTION;CYCLOMATIC;20;8 Empty function;FUNCTION;NOOPUSED|NORET;==3.14;==0

.mconf ファイルをインポートして解析すると、デフォルトの kwcheck 出力は次のようになります。

1 <path>/example2.c:6 METRICS.W.Empty_function Analyze Violated metric "Empty_function": hello 0==0

組み込みタイプのサイズの指定

注: このセクションで説明する BYTES*** メトリックの計算はすべて、C/C++ プロジェクト専用です。

Klocwork 解析を実行すると、サポートされているメトリックがすべて計算され、tables ディレクトリにある metric.dat ファイルに保存されます。ただし、レポートには、メトリックしきい値構成ファイルに規則があるメトリックしきい値の違反だけが表示されます。

Klocwork にさらに多くのメトリックについて報告させるには、追加のメトリックしきい値規則を書き、それらをメトリックしきい値構成ファイルに追加する必要があります。

しかし、追加情報を提供してメトリックが正確に計算されるようにしないと、次のメトリックに関係する新規規則を書けない場合があります。必要な情報は、Klocwork がソースコードから直接検出できる項目の範囲を超えています。

コード内の特定エンティティのバイト数を計算する次のメトリックは、追加の Klocwork オプションを使用しないと正確に計算されない場合があります。

  • BYTESGLDATADECL
  • BYTESDATADECL
  • BYTESLOCDECL
  • BYTESPARMS
  • BYTESPAROTHER

これらのメトリックの計算は、ソフトウェアシステムの組み込み型のサイズに関する保存済み情報 (バイト数単位) に依存します。組み込み型のサイズがデフォルトサイズと一致した場合、Klocwork は、実行のたびにこれらのメトリックを正確に計算します。

Klocwork 組み込み型に次のデフォルトサイズが使用されます。

Windows

char;1

signed char;1 unsigned char;1 short int;2 signed short int;2 unsigned short int;2 int;4 signed int;4 unsigned int;4 long int;4 signed long int;4 unsigned long int;4 __int8;1 __int16;2 __int32;4 __int64;8 __wchar_t;2 float;4 double;8 long double;8 <pointer>;4 <unknown type>;4

Unix:

char;1

signed char;1 unsigned char;1 short int;2 signed short int;2 unsigned short int;2 int;4 signed int;4 unsigned int;4 long int;4 signed long int;4 unsigned long int;4 long long int;8 signed long long int;8 unsigned long long int;8 float;4 double;8 long double;12 <pointer>;4 <unknown type>;4

組み込み型のサイズがデフォルトサイズと一致しない場合は、型のサイズファイルを作成し、Klocwork 解析時この構成ファイルを使用する必要があります。

  1. 任意の名前と場所を持つテキストファイルを作成します。ファイル拡張子は .sztである必要があります。
  2. このファイルの各行で、次の構文で型と型サイズを指定します。
    <type_name>;<type_size>
    フィールド
    • <type_name> は組み込み型の名前です。
    • <type_size> は型のサイズ (バイト単位) です。
  3. 次の 2 つのあらかじめ定義された型名をファイルに記載します。
    0_TYPE_POINTER は、ポインターまたはリファレンスのサイズを指定するために使用されます。
    0_TYPE_UNKNOWN は、不明な組み込み型のサイズを指定するために使用されます。
  4. 新しい構成ファイルを統合ビルド解析に適用するには、プロジェクトまたは projects_root に インポートします。

解析に対するメトリックしきい値構成ファイルの適用

新しい構成ファイルを統合ビルド解析に適用するには、プロジェクトまたは projects_root にインポートします。