このページの内容は最新ではありません。最新版の英語を参照するには、ここをクリックします。

コメント密度がしきい値を下回っている

モジュールのコメント密度が、指定されたしきい値を下回っている

R2021a 以降

このページをすべて展開する

説明

Polyspace® はファイルのコメント密度を計算するために、ファイルの実行可能行数に対するコメントの比率を算出してから、その比率を 100 で乗算します。たとえば、コメント密度が 20 の場合、これはファイルの内容の 20% がコメントで、80% がコードのステートメントであることを意味します。この欠陥は、コメント密度が指定されたしきい値を下回っている場合に報告されます。Polyspace がコメント密度を計算する方法について詳しくは、コメント密度を参照してください。

Polyspace は、ユーザーがしきい値を指定しない限り、このガイドラインでは既定のしきい値として 20 を使用します。しきい値を指定できる選択ファイルを指定するには、オプション [ファイルごとにチェッカーを設定] (-checkers-selection-file) または [チェッカー アクティベーション ファイル] (-checkers-activation-file) を使用します。

polyspace-comments-import を使用して以前の解析からコメントをインポートすると、Polyspace は以前の結果のコード メトリクスのコメント密度に関するレビュー情報を、このチェッカーの現在の結果にコピーします。現在の結果に同じコード メトリクスが含まれている場合、レビュー情報はそのコード メトリクスにもコピーされます。

リスク

このチェッカーに違反している場合は、次の可能性があります。

  • モジュールが適切にドキュメント化されていない。

  • モジュールが過剰に長く、密になっている。

  • モジュールで不測の、または計画外の状況に発展する。

これらの要因により、モジュールの保守とデバッグが困難になります。

修正方法

この欠陥を修正するには、次を行います。

  • ステートメントの間に開発者の意図を伝えるコメントを追加する。

  • または、モジュール内のステートメントの数を減らす。モジュールに複数の関数が含まれる場合、モジュールを分割して個別にドキュメント化することを検討してください。

このチェックを修正するには、コードをリファクタリングするか、チェッカーのしきい値を変更します。ベスト プラクティスは、開発後のリファクタリング コストを回避するために、開発の早期段階でモジュールの複雑度をチェックすることです。

例

すべて展開する

//File1.cpp        //Noncompliant
 long long power(double x, int n){
	 long long BN = 1;
	 for(int i = 0; i<n;++i){
		 BN*=x;
	 }
	 return BN;
 }
 
 double AppxIndex(double m, double f){
	 double U = (power(m,2) - 1)/(power(m,2)+2);
	 double V = (power(m,4) + 27*power(m,2)+38)/(2*power(m,2)+3);
	 return (1+2*f*power(U,2)*(1+power(m,2)*U*V + 
                power(m,3)/power(m,3)*(U-V)))/( (1-2*f*power(U,2)
              *(1+power(m,2)*U*V + power(m,3)/power(m,3)*(U-V))));
 }

この例では、File1.cpp 内のコードに、開発者の意図をドキュメントとして示すコメントが十分に含まれていません。開発者の意図が十分にドキュメント化されていないと、コードが理解しにくいものになります。以降のコードのデバッグと保守も困難になる可能性があります。Polyspace は、このルールに準拠していないとして、このファイルにフラグを設定します。

修正 — 開発者の意図をコメントでドキュメント化

1 つの修正方法として、十分な量のコメントを追加して開発者の意図をドキュメント化します。このコードには、開発者の意図を明確にドキュメントとして示すコメントが含まれています。このコメントが伝える情報によって、コードを理解しやすくなり、コードのデバッグと保守が容易になります。

//File1.c        //Compliant
// r = power(x,n) returns the nth power of x into y
// r is long long
// x is double
// n must be integer
 long long power(double x, int n){
	 long long BN = 1;
	 for(int i = 0; i<n;++i){
		 BN*=x;
	 }
	 return BN;
 }
 // n = AppxIndex(m,f) calculates the approximate
//  effective index of a material
// n is a double, represent the effective index of a mixture
// m is a double, represents the relative index of the 
//                  inclusion compared to the background material
// f is a double, represents the filling factor of the inclusion
// The function implements the formula in the doi 10.XXYY 
 double AppxIndex(double m, double f){
	 // This function implements the formula for approximate index
	 // The first term is U:
	 double U = (power(m,2) - 1)/(power(m,2)+2);
	 //The second term is V:
	 double V = (power(m,4) + 27*power(m,2)+38)/(2*power(m,2)+3);
	 // Calculate the denominator
	 double den = ( (1-2*f*power(U,2)*
              (1+power(m,2)*U*V + power(m,3)/power(m,3)*(U-V))));
	 // Calculate the numerator
	 double num = (1+2*f*power(U,2)
              *(1+power(m,2)*U*V + power(m,3)/power(m,3)*(U-V)));
	 // Calculate the approximate index
	 // Return by value
	 return num/den;
 }

チェック情報

グループ: ソフトウェアの複雑度
言語: C | C++
頭字語: SC02
既定のしきい値: 20

バージョン履歴

R2021a で導入

参考

| |

トピック