Comment density below threshold

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

Описание

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

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

Когда вы импортируете комментарии из предыдущих анализов при помощи polyspace-comments-importPolyspace копирует любую рецензирующую информацию о метрике кода 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