Mastering Code Clarity in C/C++: An Essential Guide to Comments

I want to give tips for the C++ language (especially C++20).?

Previously, I thought that using examples in the C# language would be a good choice as a wider range of programmers would benefit better from the examples. Programmers who create programs for Asp Net or Android (because C# is very similar to the Java language and anyone who knows Kotlin probably knows a little Java) would find it easier to understand examples written in C#.

Although Java and C# emerged as the basis for the C++ language, it seemed to me that C# was a simpler choice.?

But now, I want to give clean code tips for those who use the C++ language.

Comments in C/C++: A Comprehensive Overview?

Let's delve into a crucial aspect of C/C++ programming: comments. In many projects, you'll come across block comments, often referred to as "banners." These comments serve various purposes, from summarizing file contents to delineating specific code sections, such as class interfaces or function groups.?

However, despite their widespread use, these banners can sometimes be more distracting than helpful. Take, for instance, the "stuff.h" header file excerpt. While it offers a structured overview of the class Stuff, excessive comments like these can clutter the code, making it harder to focus on the essentials.

#ifndef _STUFF_H_
#define _STUFF_H_

// -------------------------------------
// stuff.h: the interface of class Stuff
// John Doe, created: 2007-09-21
// -------------------------------------
class Stuff {
public:
    // ----------------
    // Public interface
    // ----------------
    // ...
protected:
    // -------------
    // Overrideables
    // -------------
    // ...
private:
    // ------------------------
    // Private member functions
    // ------------------------
    // ...
    // ------------------
    // Private attributes
    // ------------------
    // ...
};
#endif        

?While these block comments are commonplace for summarizing source code contents or delineating code sections like class beginnings, they often pose more of a hindrance than assistance. However, certain scenarios, such as grouping functions of a specific category, warrant their use:

private:
// Event handlers:
void onUndoButtonClick();
void onRedoButtonClick();
void onCopyButtonClick();
// ...        

In C/C++ development, these types of comments are more prevalent (In my opinion), serving as signposts within the code. The DOOM game source code is a prime example, showcasing how block comments are used for version control and code management.

// sersetup.c
#define DOOM2
#include "sersetup.h"
//#include "serstr.h"
#include "ser_frch.h"		// FRENCH VERSION
#include "DoomNet.h"

extern	que_t		inque, outque;

void jump_start( void );
extern int 	uart;

int			usemodem;
char		startup[256], shutdown[256], baudrate[256];

extern		int baudbits;

void ModemCommand (char *str);

int		myargc;
char	**myargv;

//======================================
//
// I_Error
//
//======================================
void I_Error(char *string)
{
	printf("%s\n",string);
	exit(1);
}

/*
================
=
= write_buffer
=
================
*/

void write_buffer( char *buffer, unsigned int count )
{
	int	i;

// if this would overrun the buffer, throw everything else out
	if (outque.head-outque.tail+count > QUESIZE)
		outque.tail = outque.head;

	while (count--)
		write_byte (*buffer++);

	if ( INPUT( uart + LINE_STATUS_REGISTER ) & 0x40)
		jump_start();
}


/*
=================
=
= Error
=
= For abnormal program terminations
=
=================
*/

void Error (char *error, ...)
{
	va_list argptr;

	if (usemodem)
	{
		printf ("\n");
		printf ("\n"STR_DROPDTR"\n");

		OUTPUT(uart+MODEM_CONTROL_REGISTER, INPUT(uart+MODEM_CONTROL_REGISTER)&~MCR_DTR);
		delay (1250);
		OUTPUT( uart + MODEM_CONTROL_REGISTER, INPUT( uart + MODEM_CONTROL_REGISTER ) | MCR_DTR );
		ModemCommand("+++");
		delay (1250);
		ModemCommand(shutdown);
		delay (1250);

	}

	ShutdownPort ();

	if (vectorishooked)
		setvect (doomcom.intnum,olddoomvect);

	if (error)
	{
		va_start (argptr,error);
		vprintf (error,argptr);
		va_end (argptr);
		printf ("\n");
		exit (1);
	}

	printf (STR_CLEANEXIT"\n");
	exit (0);
}


/*
================
=
= ReadPacket
=
================
*/

#define MAXPACKET	512
#define	FRAMECHAR	0x70

char	packet[MAXPACKET];
int		packetlen;
int		inescape;
int		newpacket;

//...        

Here we see a DOOM game configuration file, where block comments are used to disable specific parts of the code or provide information about specific versions.

(Source: DOOM Repository on GitHub)

In essence, comments in C/C++ should be used judiciously to enhance code clarity and organization. While they can provide valuable insights, excessive or unnecessary comments can clutter the codebase. Striking the right balance ensures that comments serve their intended purpose without detracting from code readability and maintainability.

Other articles about "Clean Code"