Main Content

CERT C: Rec. MSC04-C

Use comments consistently and in a readable fashion

expand all in page

Description

Rule Definition

Use comments consistently and in a readable fashion.1

Polyspace Implementation

The rule checker checks for Use of /* and // within a comment.

Examples

expand all

Issue

The issue occurs when you use the character sequences /* and // within a comment.

You cannot annotate this rule in the source code. For information on annotations, see Annotate Code and Hide Known or Acceptable Results.

Risk

These character sequences in code comments might indicate an unexpected error. For instance:

  • If your code contains a /* or a // in a /* */ comment, it typically means that you have inadvertently commented out code.

  • If your code contains a /* in a // comment, it typically means that you have inadvertently uncommented a /* */ comment.

  • Your code contains nested comments. Such comments are confusing and might lead to developer confusion.

Example - /* Used in // Comments
int x,y,z,o;


void non_compliant_comments ( void )
{
	x = y //  	/* Noncompliant
	+ z
	//  */
	;
	x = y//**/ z //Noncompliant
	+o;	
	x = y //*divisor:*/z  //Noncompliant
	+o;
	
	z++;	//	Compliant with exception: // permitted within a // comment
}

void compliant_comments ( void )
{
	x = y /*  	Compliant
	+ z
	*/
	;
	x = y / /*divisor:*/ z //Compliant
	+o;	
	z++;	//	Compliant with exception: // is permitted within a // comment
}

In this example, in the non_compliant_comments function, :

  • In the first definition of x, the /* character occurs in what appears to be a // comment, violating the rule. Because of the comment structure, the operation that takes place is x = y + z;. However, without the two //-s, an entirely different operation x=y; takes place. It is not clear which operation is intended.

  • In the second and third definition of x, the presence of the characters /* in what appears to be a // comment raises violations of this rule. Because of the confusing comment placement, x is defined as y+o in these statements, instead of x = y/z + o, as intended.

Use a comment format that makes your intention clear. For instance, in the compliant_comments function:

  • In the first definition of x, it is clear that x is defined as x = y and the rest of the code is deliberately commented out;

  • In the second definition of x, it is clear x is defined as x = y/z+o. The placement of the comment /*divisor*/ is clear and does not hinder code understanding.

it is clear that the operation x=y; is intended.

Check Information

Group: Rec. 48. Miscellaneous (MSC)

Version History

Introduced in R2019a

expand all

See Also

Topics

External Websites

1 This software has been created by MathWorks incorporating portions of: the “SEI CERT-C Website,” © 2017 Carnegie Mellon University, the SEI CERT-C++ Web site © 2017 Carnegie Mellon University, ”SEI CERT C Coding Standard – Rules for Developing safe, Reliable and Secure systems – 2016 Edition,” © 2016 Carnegie Mellon University, and “SEI CERT C++ Coding Standard – Rules for Developing safe, Reliable and Secure systems in C++ – 2016 Edition” © 2016 Carnegie Mellon University, with special permission from its Software Engineering Institute.

ANY MATERIAL OF CARNEGIE MELLON UNIVERSITY AND/OR ITS SOFTWARE ENGINEERING INSTITUTE CONTAINED HEREIN IS FURNISHED ON AN "AS-IS" BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED, AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR PURPOSE OR MERCHANTABILITY, EXCLUSIVITY, OR RESULTS OBTAINED FROM USE OF THE MATERIAL. CARNEGIE MELLON UNIVERSITY DOES NOT MAKE ANY WARRANTY OF ANY KIND WITH RESPECT TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT INFRINGEMENT.

This software and associated documentation has not been reviewed nor is it endorsed by Carnegie Mellon University or its Software Engineering Institute.