exponenta event banner

Плотность комментариев ниже порогового значения

Плотность комментариев модуля ниже заданного порога

Описание

Polyspace ® вычисляет процент плотности комментариев файла, беря отношение комментариев к числу исполняемых строк в файле и затем умножая отношение на 100. Например, плотность комментариев20 указывает, что файл содержит 20% комментариев и 80% инструкций кода. Этот дефект возникает, когда плотность комментариев падает ниже указанного порога. Дополнительные сведения о том, как Polyspace вычисляет плотность комментариев, см. в разделе Comment Density

В Полиспейсе используется пороговое значение по умолчанию 80, если не указано пороговое значение. Использовать Set checkers by file (-checkers-selection-file) для указания файла выбора, в котором можно задать пороговое значение. См. Снижение сложности программного обеспечения с помощью средств проверки в полиспейсе.

При импорте комментариев из предыдущих анализов с помощью polyspace-comments-import, Polyspace копирует любую информацию о проверке в метрике кода Comment Density в предыдущем результате для этой проверки в текущем результате. Если текущий результат содержит ту же метрику кода, информация проверки также копируется в метрику кода.

Риск

Нарушение этой проверки может указывать на то, что:

  • Модуль не документирован должным образом.

  • Модуль слишком длинный и плотный.

  • Модуль может содержать непредвиденную или незапланированную разработку.

Эти факторы затрудняют обслуживание и отладку модуля.

Зафиксировать

Чтобы устранить этот дефект:

  • Поместите дополнительные комментарии между инструкциями, которые передают намерения разработчика.

  • Либо уменьшите количество операторов в модуле. Если модуль содержит несколько функций, рассмотрите возможность разделения модуля и документирования их отдельно.

Чтобы исправить эту проверку, выполните рефакторинг кода или измените порог проверки. Передовой практикой является проверка сложности модуля на ранних этапах разработки, чтобы избежать дорогостоящего рефакторинга после разработки.

Примеры

развернуть все

//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 помечает файл как несоответствующий этому правилу.

Исправление - Документирование намерений Разработчика с комментариями

Одним из возможных исправлений является документирование намерений разработчика путем внесения достаточных комментариев. Этот код содержит комментарий, который четко документирует намерения разработчиков и передает информацию, облегчающую понимание, отладку и обслуживание кода.

//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 aproximate index
	 // Return by value
	 return num/den;
 }

Проверить информацию

Группа: Сложность программного обеспечения
Язык: C | C++
Акроним: SC02
Порог по умолчанию: 20
Представлен в R2021a