コードへの注釈付けと既知の結果または許容可能な結果の非表示

コードの Polyspace^® 解析で既知の欠陥、許容可能な欠陥、またはコーディングルール違反が検出された場合、以降の解析でその欠陥や違反を非表示にできます。問題をレビュー済みで、その問題を修正しないことを示すコード注釈を追加します。

注釈は、Polyspace ユーザーインターフェイス (または IDE プラグイン) のメニュー項目を使用するか、コードに直接入力することで追加できます。注釈を追加するための一般的なワークフローについては、以下を参照してください。

Polyspace デスクトップユーザーインターフェイスで、Polyspace ユーザーインターフェイスでのバグ修正または正当化による結果への対処を参照してください。
Polyspace Platform ユーザーインターフェイスで、Polyspace Platform ユーザーインターフェイスでのバグ修正または正当化による結果への対処を参照してください。
Polyspace Access™ Web インターフェイスで、Polyspace Access でのバグ修正または正当化による結果への対処 (Polyspace Access)を参照してください。
IDE で Polyspace as You Code プラグインまたは拡張機能を使用している場合は、IDE での Polyspace as You Code 結果のレビューを参照してください。
Simulink^® でブロックレベルの注釈を使用している場合は、Simulink ブロックに注釈を付けて Polyspace の結果に対処を参照してください。

このトピックでは、注釈構文を説明します。

Code Prover によってソースコード内で検出されたランタイムエラーは、コード注釈を追加しても非表示にはできないことに注意してください。ただし、他のすべての結果と同様に、ランタイムエラーと関連付けられたレビュー情報は対応するコード注釈から抽出され、結果と共に表示されます。

コード注釈構文

コメントをソースファイルに直接入力するには、Polyspace 注釈構文を使用します。この構文では大文字と小文字を区別しません。形式は次のとおりです。/* */ で囲まれた C スタイルのコメントと // で始まる C++ スタイルのコメントの両方がサポートされています。

1 行のコードへの注釈付け

現在のコード行 (マクロ内を含む) に対する結果に注釈を付けるには、以下の構文を使用します。

line of code; /* polyspace Family:Result_name */

読みやすくするためにコロン (:) の前後に空白を追加できます。次に例を示します。

var++; /* polyspace DEFECT : INT_OVFL */

注釈はキーワード polyspace で始まります。注釈には、Family および Result_name フィールド値を含めなければなりません。

オプションで、Status、Severity、および Comment フィールド値を指定できます。

polyspace Family:Result_name [Status:Severity] "Comment"

次に例を示します。

var++; /* polyspace DEFECT:INT_OVFL [Justified:Low] "Overflow taken into account."*/

ステータスを指定しない場合、Polyspace では結果が正当化されていると見なし、結果にステータス [No action planned] を割り当てます。

詳細は、注釈構文の詳細および構文の例を参照してください。

コードブロックへの注釈付け

コードブロックに注釈を付けるには、以下の構文を使用します。注釈はコードブロック自体にのみ適用され、ブロックから呼び出される関数の本体には適用されないことに注意してください。

現在のコード行とそれに続く n 行に対する注釈:
```
line of code; /* polyspace +n Family : Result_name */
```

コードブロックに対する注釈:

/* polyspace-begin Family : Result_name */
{
   block of code
}
/* polyspace-end Family : Result_name */

必要に応じて、ステータス、重大度、およびコメントを指定します。

同じ Family と Result_name の結果に対する注釈が入れ子になっている場合、最も内側の注釈が使用されます。

たとえば、次のコードでは、9 行目の注釈がブロック注釈の代わりに適用されますが、7 行目の違反にはブロック注釈が適用されます。

1  /*polyspace-begin MISRA-C : 14.9 [To fix:High] */
2  int main(void) 
3  {
4      int x = 1;
5      int y = x / 2;
6  
7      if (y < 0) /* Block annotation is applied to this violation of MISRA-C:14.9*/
8          y++;
9      if (x > y) /*polyspace MISRA-C : 14.9 [Justified:Low] */
10         return x;
11     return x;
12 }
13 /*polyspace-end MISRA-C : 14.9 [To fix:High] "Block annotation"*/

注釈を複数のデータ行に適用する場合、その注釈はコード内のグリーンチェックには適用されません。解析を再実行した場合、これらのグリーンチェックは正当化済みとは見なされず、[結果のリスト] 内の Status と Severity は、注釈の Status と Severity に変更されません。

コードブロックに注釈を付けると、そのブロック内で発生した問題のみに注釈が適用されます。たとえば、注釈が付いたブロックの中に関数呼び出しがあり、その関数本体で違反が発生するとします。この違反は、関数が呼び出されるコードブロック外にある、注釈の影響は受けません。

詳細は、注釈構文の詳細および構文の例を参照してください。

同じコード行での複数の結果の正当化

コード行に複数の結果が含まれている場合は、次の構文を使用してその結果を正当化できます。

結果が同じファミリに属している場合は、結果名をコンマで区切って指定します。
```
line of code; /* polyspace Family : Result_1_name,Result_2_name */
```
結果が異なるファミリに属している場合は、ファミリ名をスペースで区切って指定します。
```
line of code; /* polyspace Family_1 : Result_1_name Family_2 : Result_2_name */
```

必要に応じて、ステータス、重大度、およびコメントを指定します。

詳細は、注釈構文の詳細および構文の例を参照してください。

メモ

Polyspace は、注釈の解析時に二重引用符で囲んだテキストの後に続くすべてのものを無視します。二重引用符で囲んだテキストの後に追加の注釈を適用するには、polyspace キーワードを再度入力します。以下に例を示します。

/* polyspace Family_1 : Result_1_name "comment 1" polyspace Family_2 : Result_2_name "comment 2"*/

注釈構文の詳細

さまざまな注釈フィールドを指定可能な値に置き換えるには、この表の値を参照するか、例を参照してください。

フィールド	指定可能な値
`Family`	解析結果のタイプ: `DEFECT` (Polyspace Bug Finder™) `RTE` (実行時チェック (Polyspace Code Prover™) の場合) `CODE-METRICS` (関数レベルのコード複雑度メトリクスの場合) `VARIABLE` (グローバル変数 (Polyspace Code Prover) の場合) `MISRA-C` または `MISRA2004` (MISRA C™:2004 ルール違反の場合)。これらの注釈は、2 つの規約間のマッピングに基づいて、MISRA C:2012 違反にも適用されます。このマッピングにより、新しい規約に移行する際に古い規約の正当化を再利用できます。以前の標準から新しい標準への正当化のインポートを参照してください。 `MISRA-AC-AGC` (生成されたコードに適用できる MISRA C:2004 ルールに対する違反の場合) `MISRA-C3` または `MISRA2012` (MISRA C:2012 ルール違反の場合)。注釈は、生成されたコードに適用できるルールの場合にも機能します。 `MISRA-C-2023` (MISRA C:2023 ルール違反の場合)注釈は、生成されたコードに適用できるルールの場合にも機能します。 `CERT-C` (CERT^® C コーディング規約違反の場合) `CERT-CPP` (CERT C++ コーディング規約違反の場合) `CWE` (共通脆弱性タイプ一覧 (CWE) ルールの場合) `ISO-17961` (ISO/IEC TS 17961 コーディング規約違反の場合) `MISRA-CPP` (MISRA™ C++:2008 ルール違反の場合) `MISRA-CPP-2023` (MISRA C++:2023 ルール違反の場合) `AUTOSAR-CPP14` (AUTOSAR C++14 ルール違反の場合) `JSF` (JSF++ ルール違反の場合) `GUIDELINE` (ソフトウェアの複雑度のガイドラインの場合)。 `CUSTOM` (カスタムコーディングルール違反の場合) `StandardID` (ユーザー定義のコーディング規約違反の場合)ここで `StandardID` は、ユーザー定義のコーディング規約を符号化する SARIF ファイルのプロパティ `runs/taxonomies/properties/id` で指定されている短い名前です。SARIF ファイルの概要については、Create User-Defined Coding Standard by Using Polyspace Bug Finder Checkersを参照してください。すべての解析結果を指定するには、アスタリスク文字 `:` を使用します。構文の例を参照してください。
`Result_name`	`DEFECT` の場合、チェッカーの短い名前を使用します。Bug Finder 欠陥グループおよび欠陥チェッカーの短い名前を参照してください。 `RTE` の場合、実行時チェックの短い名前を使用します。Code Prover 実行時チェックの短い名前を参照してください。 `CODE-METRICS` の場合、コード複雑度メトリクスの短い名前を使用します。コード複雑度メトリクスの短い名前を参照してください。コード注釈を使用してプロジェクトおよびファイルメトリクスを正当化することはできません。 `VARIABLE` の場合は、指定可能な値はアスタリスク文字 "" だけです。コーディング規約違反の場合は、1 つ以上のルール番号を指定します。ユーザー定義のコーディング規約の場合は、ガイドライン ID を指定します。コーディング規約の各ガイドラインは、SARIF ファイルの `run/taxonomies/taxa` 配列のエントリを使用して符号化されています。ガイドラインの ID は、対応する `taxa` 要素の `id` プロパティに指定されています。SARIF ファイルの概要については、Create User-Defined Coding Standard by Using Polyspace Bug Finder Checkersを参照してください。ソフトウェアの複雑度のガイドラインの場合は、ガイドラインの頭字語を使用します。ガイドラインで個々のガイドラインに関するページを参照してください。結果名 `[MISRA2012:17.]` のすべての部分またはファミリ `[DEFECT:*]` のすべての結果名を指定するには、アスタリスク文字を使用します。構文の例を参照してください。
`Status`	コードのエラーをどのように処理するかを示すテキスト。この値は [結果のリスト] ペインの [ステータス] 列に、次のいずれかとして入ります。 `Unreviewed` `To investigate` `To fix` `Justified` `No action planned` `Not a defect` `Other` Polyspace では、`Justified`、`No action planned`、または `Not a defect` のステータスが設定された注釈付きの結果をその後の解析で表示しません。指定可能な値ではないステータスを指定した場合、Polyspace ではそれをカスタムステータスとして保存します。
`Severity`	コードのエラーがどの程度重大であるかを示すテキスト。この値は [結果のリスト] ペインの [重大度] 列に、次のいずれかとして入ります。 `Unset` `High` `Medium` `Low` 指定可能な値ではない重大度を指定した場合、Polyspace ではそれをステータスフィールドに追加して、カスタムステータスとして保存します。たとえば、`[To investigate:sporadic]` は [結果のリスト] ペインの [ステータス] 列に `[To investigate sporadic]` として表示されます。
`Comment`	キーワードやステータスと重大度に関する説明などの追加のテキスト。この値は [結果のリスト] ペインの [コメント] 列に入ります。追加のテキストはコード内で複数行にわたる可能性があります。レポートにこのテキストを表示する場合、テキスト全体を 1 つの段落として読めるように、行の先頭と末尾のスペースが 1 つのスペースに統合されます。

構文の例

単一の欠陥の非表示

欠陥と同じ行に注釈を入力し、Family (DEFECT) と Result_name (INT_OVFL) を指定します。ステータスを指定しない場合、Polyspace によってステータス No action planned が割り当てられ、以降の解析で結果が非表示になります。

int var = INT_MAX;
var++; /* polyspace DEFECT : INT_OVFL */

単一のコーディング規約違反の非表示

コーディング規約違反、たとえば、CERT-C 違反を正当化します。

違反と同じ行に注釈を入力し、Family (CERT-C) と Result_name (STR31-C などのルール番号) を指定します。ステータス Justified、重大度 Low、およびコメントを割り当てます。

line of code; /* polyspace CERT-C : STR31-C [Justified:Low] "Overflow cannot happen
                                            because of external constraints." */

複数行にわたるすべての MISRA C:2012 違反の非表示

polyspace エントリと Family:Result_name エントリの間に +n を入れて注釈を入力します。この注釈は、同じ行とそれに続く n 行に適用されます。

次の注釈は行 4 ～ 7 に適用されます。行のカウントには、コード、コメント、および空行が含まれます。

4. line of code ; // polyspace +3 MISRA2012:* 
5. //comment
6. 
7. line of code;
8. line of code;

関数に対するすべてのコードメトリクスの非表示

関数レベルのコード複雑度メトリクスに注釈を付けるには、関数定義で、関数名と同じ行に注釈を入力します。

この注釈により、関数 func のすべてのコード複雑度メトリクスが非表示になります。

char func(char param) { //polyspace CODE-METRICS:*
   ...
}

同じ注釈への複数のファミリの指定

各ファミリをスペースで区切って入力します。次の注釈はすべての MISRA C:2012 ルール 17 とすべての実行時チェックに適用されます。

line of code; /* polyspace MISRA2012 : 17.* RTE : * */

同じ注釈への複数の結果名の指定

Family (DEFECT) を指定した後、各 Result_name をコンマで区切って入力します。

system("rm ~/.config"); /* polyspace DEFECT:UNSAFE_SYSTEM_CALL,RETURN_NOT_CHECKED */

グローバル変数の使用を示す結果を非表示にする

グローバル変数の使用を示す Code Prover の結果 (未使用のグローバル変数など) を正当化するには、変数宣言の横に注釈を入力します。

たとえば、Justified ステータス、重大度 Low、およびいくつかのコメントを含むグローバル変数の結果を非表示にするには、注釈を次のように入力します。

int var; /* polyspace VARIABLE:* [Justified: Low] "Storage repo for later use"*/

注釈への説明コメントの追加

Family と Result_name を指定した後、正当化に関する追加情報を含む Comment を追加できます。コメントは、すべてのファミリと結果名に提供することも、ファミリと結果名ごとに提供することもできます。

すべての結果に同じコメントを使用する場合:


line of code; /* polyspace DEFECT : BAD_FREE MISRA2004:* "Comment for defect and MISRA" */

異なる結果に異なるコメントを使用する場合:
```
line of code; /* polyspace DEFECT:* "Defect comment" polyspace MISRA2004:5.2 "MISRA comment" */
```
Polyspace は注釈を解析するときに、二重引用符で囲んだテキストの後に続くすべてのものを無視します。同じコード行で追加の結果に注釈を付けるには、二重引用符で囲んだテキストの後に polyspace キーワードを入力します。

ステータスと重大度の設定

ステータスと重大度に指定可能な値を指定するか、カスタム値を入力できます。カスタム重大度エントリはステータスに追加され、ユーザーインターフェイスのカスタム [ステータス] として保存されます。

//Set Status only
line of code; /* polyspace DEFECT:* [To fix] "some comment" */

//Set Status 'To fix' and Severity 'High'
line of code; /* polyspace VARIABLE:* [To fix: High] "some comment"*/

//Set custom status 'Assigned' and Severity 'Medium'
line of code; /* polyspace MISRA2012:12.* [Assigned: Medium] */

コードブロックでの違反の正当化

コードブロックで発生した違反を正当化するために注釈を使用します。たとえば、次のコードを考えます。

double foo(void){
	constexpr int speedLimit = 65;
	constexpr double coeff = 0.2;
	int flag{0};
	int negOne{-1};
	//... 
	return (flag)?speedLimit*coeff*negOne
	: speedLimit*coeff*negOne - 35; //Noncompliant
}

int main(){
	
	/* polyspace-begin AUTOSAR-CPP14:A5-1-1 [Justified: Low]"Known Constant"*/
	//....
	for(int i = 0; i<10;++i){
		foo();
		//...
	}
	
	/* polyspace-end AUTOSAR-CPP14:A5-1-1  [Justified: Low]"Known Constant"*/
	return 1;
}

for ループには、ループ境界としてハードコードされたリテラルがあり、これは [AUTOSAR C++14 Rule A5-1-1] の違反です。構文 /*polyspace begin...*/ {...}/*polyspace-end...*/ でそのブロックに注釈を付けることによって、結果のリストでは行 for(int i = 0; i<10;++i){ の違反は正当化された欠陥として表示されます。

注釈が付いたブロックには、関数 foo() への呼び出しが含まれます。この注釈はこの関数の本文には適用されません。たとえば、foo() の return ステートメントにある違反は未確認の欠陥として表示されます。

結合された行での結果への注釈付け

結合されたコード行に表示される結果に注釈を付けます。次のコードについて考えます。

#include <stdio.h>

#define NULL_PTR ((void*)0)

extern  int *value; 
extern int *ptr[10];
void callfoo(int **);

void t1(int val) {
  callfoo(&value);
    /* polyspace +1 RTE:OVFL */
    printf("Dereferenced value: %d %d %d %d\n", NULL_PTR, *ptr[val], *value+val, \
  val);
}

結合された行での実行時チェック [オーバーフロー] は、以降のレビューでは抑制されます。

コード注釈の警告

コード注釈を誤って入力した場合、または注釈が適用されなくなった場合には、解析ログに警告が記録されます。

Warning: These Polyspace annotations do not apply to the current code

警告は次のいずれかを示しています。

コード修正、または解析構成の変更により、問題が検出されなくなった。
たとえば、次の注釈があるとします。
```
/* polyspace RTE:IDP [No action planned:Low] */
```
[不適切にデリファレンスされたポインター] チェック (IDP として注釈がつけられている) が以前はレッドまたはオレンジでしたが、現在ではグリーンであるために、この注釈は適用されなくなった可能性があります。
注釈構文が正しくない。
polyspace で始まり、その後に 1 つの単語と : (コロン) が続く次のような注釈があるとします。
```
// polyspace Family: 
```
この注釈は、結果を正当化する Polyspace 注釈と見なされます。polyspace の後に続く単語 Family が、Polyspace の結果のタイプ (DEFECT や RTE など) ではない場合、解析ではこの注釈が無効であると解釈され、警告が表示されます。たとえば、次の注釈では警告がトリガーされます。
```
// polyspace TODO: Fix in March dev cycle
```
これは、TODO が Polyspace 結果のタイプではないためです。このような警告を回避するには、コロンの代わりに別の区切り文字などを使用します。すべての結果のタイプは、コード注釈構文を参照してください。

コード注釈を無視する

場合によっては、結果がまだレビューされていない場合などのように、クリーンな解析を実行する必要があることがあります。たとえば、以前に正当化されたすべての結果が表示される、ワーストケース解析を実行する場合です。

オプション -ignore-code-annotations を使用すると、履歴なしでこのような解析を実行できます。この解析ではコード注釈が無視され、注釈付きの結果がすべて表示されますが、注釈から取得されるレビュー情報は表示されません。

-ignore-code-annotations も参照してください。

参考

-xml-annotations-description | -ignore-code-annotations