How to make clang-format skip sections of c++ code

Question

Is there any way to configure the clang-format tool to skip my Qt::connect function calls ? There are several connects in my constructors which looks like these:

connect( m_Job, SIGNAL( error( const QString&, const QString& ) ),  this, SLOT( onError( const QString&, const QString& ) ) );
connect( m_Job, SIGNAL( message( const QString& ) ),                this, SLOT( onMessage( const QString& ) ) );
connect( m_Job, SIGNAL( progress( int, int ) ),                     this, SLOT( onProgress( int, int ) ) );

but after I run the formatting tool it makes it less readable:

connect( m_Job, SIGNAL( error(const QString&, const QString&)), this, SLOT( onError(const QString&, const QString&)) );
connect( m_Job, SIGNAL( message(const QString&)), this, SLOT( onMessage(const QString&)) );
connect( m_Job, SIGNAL( progress(int, int)), this, SLOT( onProgress(int, int)) );

Answer 1

Use // clang-format off and // clang-format on to make it skip code sections.

// clang-format off
// Don't touch this!
connect( m_Job, SIGNAL( error( const QString&, const QString& ) ),  this, SLOT( onError( const QString&, const QString& ) ) );
connect( m_Job, SIGNAL( message( const QString& ) ),                this, SLOT( onMessage( const QString& ) ) );
connect( m_Job, SIGNAL( progress( int, int ) ),                     this, SLOT( onProgress( int, int ) ) );
// clang-format on
// Carry on formatting

Answer 2

As an aside: You should be normalizing the signal/slot signatures. Thus, the references and const-references are not needed, the signature normalization code within Qt simply removes them. You also don't need the third parameter if it's this.

Your code should look as follows:

connect(m_Job, SIGNAL(error(QString,QString)), SLOT(onError(QString,QString)));
connect(m_Job, SIGNAL(message(QString)), SLOT(onMessage(QString)));
connect(m_Job, SIGNAL(progress(int,int)), SLOT(onProgress(int,int)));

If you insist, there certainly can be spaces between the parameter types, at some runtime cost of course since the normalization code isn't a no-op anymore.

You can also leverage QMetaObject::connectSlotsByName to get rid of explicit connections. This requires that m_Job is a child of this, and has a name. For example:

class Foo : public Q_OBJECT {
  Job m_job;
  Q_SLOT void on_job_error(const QString&, const QString&);
  Q_SLOT void on_job_message(const QString&);
  Q_SLOT void on_job_progress(int, int);
public:
  Foo(QObject * parent = 0) :
    QObject(parent),
    m_job(this)
  {
    m_job.setObjectName("job");
    QMetaObject::connectSlotsByName(this);
  }
};

The slots with names having the pattern on_name_signal will be automatically connected by connectSlotsByName. The name is the name of the sender object, and signal is the name of the signal.

Finally, the excessive whitespace can make your code harder, not easier, to read. This is not an issue of style, but of simple physiology. Fovea centralis is about 2 angular degrees in diameter. One angular degree of vision is about the width of your thumb at arms' length. Reading code with excessive whitespace requires more saccades/fixations to relocate your central vision along the line of code. Figure 0.15-0.2s needed to process each fixation's worth of data and integrate it with your mental model of the code you're reading. It's all measurable.

As an anecdote, not medical advice: I can't read dense sheet music without +0.5 glasses on my nose. My vision is otherwise completely normal. YMMV.