Chapter 4 Basics of Clean C++

only one, but one of many places where code has been commented out. The code will soon turn into a big mess and the commented-out code snippets will add a lot of noise that impedes readability. Furthermore, commented-out code snippets are not quality assured, that is, they are not translated by the compiler, not tested, and not maintained.

Note  Except for the purpose to try out something quickly, don’t use comments to disable code. There is a version control system!

If code is no longer used, simply delete it. Let it go. You have a “time machine” to get it back, if necessary: your version control system. However, it often turns out that this case is very rare. Just take a look at the timestamp the developer added in the example in Listing 4-13. This piece of code is age old. What is the likelihood that it will ever be needed again?

To try out something quickly during development, such as when searching for the cause of a bug, it is of course helpful to comment out a code section temporarily. But it must be ensured that such modified code is not checked into the version control system and accidentally comes into production.

Don’t Write Block Comments

Comments like the ones shown in Listing 4-14 are found in many projects.

Listing 4-14.  An Example of Block Comments

#ifndef _STUFF_H_ #define _STUFF_H_

// -------------------------------------

//stuff.h: the interface of class Stuff

//John Doe, created: 2007-09-21

// -------------------------------------

class Stuff { public:

// ----------------

// Public interface // ----------------

80

Chapter 4 Basics of Clean C++

// ...

protected:

// -------------

//Overrideables

//-------------

//...

private:

// ------------------------

//Private member functions

//------------------------

//...

// ------------------

//Private attributes

//------------------

//...

};

#endif

These kinds of comments (and I do not mean the ones I used to obscure irrelevant parts) are called “block comments,” or “banners.” They are often used to add a summary about the content at the top of a source code file. Or they are used to mark a special position in the code. For instance, they introduce a code section where all private member functions of a class can be found.

These kinds of comments are mostly pure clutter and should be deleted immediately!

There are very few exceptions where such comments could have a benefit. In some rare cases, a bunch of functions of a special category can be gathered together underneath such a comment. But then you should not use noisy character trains

consisting of hyphens (-), slashes (/), number signs (#), or asterisks (*) to envelop them. A comment like the one in Listing 4-15 is absolutely sufficient to introduce such a region.

81

Chapter 4 Basics of Clean C++

Listing 4-15.  Sometimes Useful: a Comment to Introduce a Category of Functions

private:

// Event handlers:

void onUndoButtonClick(); void onRedoButtonClick(); void onCopyButtonClick(); // ...

#PRAGMA REGION/#PRAGMA ENDREGION

So-called #pragma directives provide a way to specify compiler-, machine-, and operating system-specific functionality while maintaining overall compatibility with the C++ language. For example, many C++ compilers support the #pragma once directive, which ensures that a (header) file is included only once and thus offers an alternative to macro-based include guards.

Using the #pragma region <name-of-region> directive and its corresponding #pragma endregion directive, developers can specify a block of code that can be expanded or collapsed when the IDE has a so-called folding editor that supports it. The code example from Listing 4-15 would then look like this:

#pragma region EventHandler void onUndoButtonClick(); void onRedoButtonClick(); void onCopyButtonClick();

#pragma endregion

In some projects the coding standards say that big headers with copyright and license text at the top of any source code file are mandatory. They can look like Listing 4-16.

82

Chapter 4 Basics of Clean C++

Listing 4-16.  The License Header in Any Source Code File of Apache OpenOffice 3.4.1

/**************************************************************

*

*Licensed to the Apache Software Foundation (ASF) under one

*or more contributor license agreements. See the NOTICE file

*distributed with this work for additional information

*regarding copyright ownership. The ASF licenses this file

*to you under the Apache License, Version 2.0 (the

*"License"); you may not use this file except in compliance

*with the License. You may obtain a copy of the License at

*http://www.apache.org/licenses/LICENSE-2.0

*

*Unless required by applicable law or agreed to in writing,

*software distributed under the License is distributed on an

*"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

*KIND, either express or implied. See the License for the

*specific language governing permissions and limitations

*under the License.

*

*************************************************************/

First, I want to say something fundamental about copyrights. You don’t need to add comments about the copyright, or do anything else, to have copyright over your works. According to the Berne Convention for the Protection of Literary and Artistic Works

[Wipo1886] (or Berne Convention in short), such comments have no legal meaning. There were times where such comments were required. Before the United States had signed the Berne Convention in 1989, such copyright notices were mandatory if

you wanted to enforce your copyright in the United States. But that is a thing of the past. Nowadays these comments are no longer needed.

My advice is to simply omit them. They are just cumbersome and useless baggage. However, if you want to, or even need to offer copyright and license information in your

83