Comment density below threshold

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

Описание

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

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

Когда вы импортируете комментарии из предыдущих исследований при помощи 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

Смотрите также

Check Guidelines (-guidelines)

Темы

Введенный в R2021a

Документация