
			/
			home
			/
			Programming
			/
			Style
			/

Classes

Classes are central to developing everything as an API; a style that maximizes readability.

How does it maximize readability? ^§

A class header is its blueprint.
Written properly, intended use is easily understood.


#ifndef QOAUTH2_H
#define QOAUTH2_H

#include <QObject>

class QOAuth2 : public QObject
{
Q_OBJECT
public:
        explicit QOAuth2( QObject *parent = nullptr );
        ~QOAuth2();
        QString getToken( const QString &urlForToken
        = "https://www.googleapis.com/oauth2/v4/token" );

        /* Oauth2 */
        QString access_token     ();
        QString client_id        ();
        QString client_secret    ();
        QString code             ();
        QString error            ();
        QString error_description();
        QString error_uri        ();
        QString expires_in       ();
        QString grant_type       ();
        QString password         ();
        QString redirect_uri     ();
        QString refresh_token    ();
        QString response_type    ();
        QString scope            ();
        QString state            ();
        QString token_type       ();
        QString username         ();

        void setAccess_token       ( const QString &access_token      );
        void setClient_id          ( const QString &client_id         );
        void setClient_secret      ( const QString &client_secret     );
        void setCode               ( const QString &code              );
        void setError              ( const QString &error             );
        void setError_description  ( const QString &error_description );
        void setError_uri          ( const QString &error_uri         );
        void setExpires_in         ( const QString &expires_in        );
        void setGrant_type         ( const QString &grant_type        );
        void setPassword           ( const QString &password          );
        void setRedirect_uri       ( const QString &redirect_uri      );
        void setRefresh_token      ( const QString &refresh_token     );
        void setResponse_type      ( const QString &response_type     );
        void setScope              ( const QString &scope             );
        void setState              ( const QString &state             );
        void setToken_type         ( const QString &token_type        );
        void setUsername           ( const QString &username          );

signals:
        void access_tokenChanged     ();
        void client_idChanged        ();
        void client_secretChanged    ();
        void codeChanged             ();
        void errorChanged            ();
        void error_descriptionChanged();
        void error_uriChanged        ();
        void expires_inChanged       ();
        void grant_typeChanged       ();
        void passwordChanged         ();
        void redirect_uriChanged     ();
        void refresh_tokenChanged    ();
        void response_typeChanged    ();
        void scopeChanged            ();
        void stateChanged            ();
        void token_typeChanged       ();
        void usernameChanged         ();

private:
        QString m_Access_token     ;
        QString m_Client_id        ;
        QString m_Client_secret    ;
        QString m_Code             ;
        QString m_Error            ;
        QString m_Error_description;
        QString m_Error_uri        ;
        QString m_Expires_in       ;
        QString m_Grant_type       ;
        QString m_Password         ;
        QString m_Redirect_uri     ;
        QString m_Refresh_token    ;
        QString m_Response_type    ;
        QString m_Scope            ;
        QString m_State            ;
        QString m_Token_type       ;
        QString m_Username         ;
};

#endif // QOAUTH2_H

How to read a class? ^§

Infer purpose from name.
Check if subclassing QObject
Note getters and setters.
Note regular functions.
Note signals [Applies to QObjects].

How was the above class read? ^§

Name inferred OAuth2.
Subclasses QObject.
public getters and setters for all members.
One regular function: QOAuth2::getToken.
All signals are for setters. No special signals otherwise.

Therefore? ^§

Understanding OAuth2 is a pre-requisite.
Treat as an API. Consider subclassing.
Create an instance and monitor changes.
Try running QOAuth2::getToken.
See what happens.

If that does not work? ^§

Ideally the function should inform you what was insufficient.
Also note QOAuth2::error()

Anything else? ^§

No. The class is very straightforward.

How should one design a class? ^§

Subclass QObject.
Design as API.

What does an API contain at minimum? ^§

Getters for all member variables.
Setters for external control.

What does QObject do for an API? ^§

Enables a signal / slot framework.
Good signals notify member changes and significant events.
Allows for precise code insertion:


/* A class designed as an API */
class Sneed : public QObject
{
        Q_OBJECT
public:
        int feed();

signals:
        void feedChanged();

private:
        int m_Feed;
};


/* Interfacing with that class's API */
int main()
{
        Sneed sneed;

        QObject::connect( &sneed, &Sneed::feedChanged, [&sneed](){
                // whenever m_Feed changes
                // this code will execute:
                qDebug() << sneed.feed();
        }
}

When do you make an exception with QObject? ^§

When objects absolutely need to be copyable.

Copyable and Non-copyable objects

A copyable object in real life: ^§

Imagine a teacher distributes 30 copies of a worksheet.
No matter how one modifies a particular copy, all others remain unaffected.

A copyable object in programming: ^§

Imagine a text document is copied then modified.
No matter how one modifies the copy, the original remains unaffected.

A NON-copyable object in real life: ^§

Imagine a telephone pole connected to a house.
Copying that pole will leave two identical telephone poles connected to one house.
The presence of a second pole will interfere with the intended function of the first.

A NON-copyable object in programming: ^§

Imagine copying a download in progress.
Two downloads of the same source are now appending data to one file.
The file will be corrupted with redundant data.

Should one still develop non-copyable classes as APIs? ^§

Yes: even without signals/slots, always use getters and setters.

Encapsulization Rules

public: ^§

Never make a member variable public.
Create public getter functions instead.
Only change members via setters:


/* Bad */
class Sneed
{
public:
        Feed  m_Feed;
        Seed *m_Seed;
        static const inline Chuck s_Chuck{1};
};

/* Good */
class Sneed
{
public:
        Feed  feed() const;
        Seed *seed() const;

        void setFeed( const Feed &feed );
        void setSeed(       Seed *seed );

        // Acceptable
        static const inline Chuck s_Chuck{1};

private:
        Feed  m_Feed;
        Seed *m_Seed{nullptr};
};

Why use getter functions? ^§

Easily modifiable.

What would I modify it for? ^§

Adding a mutex, to make it thread safe.
Debugging.

protected: ^§

Place all internal functions here.

Why not in private:? ^§

Do so if intended to be only run once:


/* Bad */
class Sneed
{
private:
        void clear();
        void reset();
        void update();
        void initiate();
};

/* Good */
class Sneed
{
protected:
        void clear();
        void reset();
        void update();

private:
        void initiate();
};

private: ^§

Place all member variables here.
Prefix member variables like so:

 d_[directory]
 f_[file     ]
 m_[member   ]
mn_[magic #  ]
 p_[process  ]
re_[regex    ]
 s_[static   ]
db_[database ]

( Use g_[global] for global scope. )

What about custom prefixes? ^§

Encouraged if a particular special type or context appears very often in a single class:
j_[Javascript] IE scripts for code injection.
si_[QStandardItem] IE particular table items.


/* Bad */
int fancy;
class Sneed
{
public:
        Sneed() {
                Q_ASSERT( m_query.contains( QRegularExpression("(!i)(feed|seed)") ) );
                QTextStream(stdout) << 9001;
        }
private:
        QDir m_seed;
        QFile *pHobo; // p is hungarian notation for pointer
        QString feed;
        QProcess m_Rsync;
        static int m_Chuck;
        QDatabase store;

        QString m_Query;
};

/* Good */
int g_Fancy;
class Sneed
{
public:
        Sneed()
        {
                Q_ASSERT( m_query.contains( re_FeedOrSeed ) );
                QTextStream(stdout) << mn_PowerLevel;
        }

private:
        QDir       d_Seed ; // d  is for Directory
        QFile     *f_Hobo ; // f  is for File
        QString    m_Feed ; // m  is for Member
        QProcess   p_rsync; // p  is for Process
        static int s_Chuck; // s  is for Static
        QDatabase db_Store; // db is for Database

        QString    j_Query; // j  is an informal custom prefix for Javascript
        QString    m_Query; // Prefer m if it's context appears once
        static inline const int mn_PowerLevel{9001};
        static inline const QRegularExpression re_FeedOrSeed{"(!i)(feed|seed)"};
};

What are the points of these prefixes? ^§

Assists with IDE code autocompletion.
Distinguishes them from local objects
Local objects can be given d_|f_|p_ prefix because those prefixes are defferring to a special type.
If short lived, prefer a singlular letter:


/* Bad */
Sneed::Sneed()
{
        QDir  dir("/proc/");
        QFile file1( dir.absoluteFilePath("feed.txt") );
        QFile file2( dir.absoluteFilePath("seed.txt") );
        int m_Number = 911; // m_ here is heresy

        for ( int i = 0; i < --m_Number; i++ ) {
                QString str = QString::number(i);
                QProcess ps;
                ps.start( "ps", QStringList() << str );
                ps.waitForFinished();

                if ( file1.open( QIODevice::ReadOnly  )
                  && file2.open( QIODevice::WriteOnly ) ) {
                        file2.write( file1.readAll() + ps.readAll() );
                }
                file1.close();
                file2.close();
        }
        qDebug() << m_Number;
}

/* Good */
Sneed::Sneed()
{
        QDir  d("/proc/");
        QFile f_Feed( d.absoluteFilePath("feed.txt") );
        QFile f_Seed( d.absoluteFilePath("seed.txt") );
        int n = 911;

        for ( int i = 0; i < --n; i++ ) {
                QString s = QString::number(i);
                QProcess p;
                p.start( "ps", QStringList() << s );
                p.waitForFinished();

                if ( f_Feed.open( QIODevice::ReadOnly  )
                  && f_Seed.open( QIODevice::WriteOnly ) ) {
                        f_Seed.write( f_Feed.readAll() + p.readAll() );
                }
                f_Feed.close();
                f_Seed.close();
        }
        qDebug() << n;
}

(public|protected|private) slots: ^§

Enabled by QObject.
No longer required for Qt5+.
Adds compatibility for Qt4, QML, QMetaObject, Javascript Classes.
Always use for functions intended as slots.
Name function after signal, prefix with 'on':


/* Good */
class Sneed : public QObject
{
        Q_OBJECT
signals:
        void feedChanged();
        void finished( bool success );

protected slots:
        void onFeedchanged();
        void onFinished( bool success );
};

signals: ^§

Enabled by QObject.
Create a signal for each setter.
Create a signal for any significant event:


/* Good */
class Sneed : public QObject
{
        Q_OBJECT
public:
        void setFeed( QString s );
        void setSeed( QString s );

signals:
        void feedChanged();
        void seedChanged();

        void started ();
        void paused  ();
        void finished();
        void opened  ();
        void closed  ();
        void ready   ();
        void errorOccured();
};

Keywords and Qualifiers

explicit ^§

Mark all QObject constructors explicit to prevent copying,

friend ^§

Avoid unless absolutely neccessary.
Prefer setters.

auto ^§

Never use except in templates.
See: Programming/Style/auto.html

class struct union [Nested Classes] ^§

Always encapsulate in private: or protected:.
Prefer unions and structs.
Use to reduce name pollution:


/* Good */
class Sneed
{
public:
        QString output();

private:
        struct Container
        {
                QTime    time  ;
                QString  output;
                QThread *thread;
        }
        QList<Container> m_ContainerList;

        QTime m_Time;
}

const ^§

Use wherever possible.
Mark all getter functions const.
Only use west const:


/* Bad */
Feed const *m_Feed;

/* Good */
const Feed *m_Feed;

enum ^§

Define in class unless externally relevant.
Prefer enums over strings, with QMetaEnum:


/* Bad */
class Convenience : public QObject
{
        Q_OBJECT
public:

        enum Store {
                none = 0x0,
                sneed = 0x1,
                feed = 0x2,
                seed = 0x4,
                chuck = 0x8,
                hobo = 0x10,
        };
        Q_ENUM(Store)
        static const inline QMetaEnum s_MetaStore{ QMetaEnum::fromType<Store>() };

        Convenience( Store store )
        {
                switch(store) {
                case none: qDebug() << "none"; break;
                case sneed: qDebug() << "sneed"; break;
                case feed: qDebug() << "feed"; break;
                case seed: qDebug() << "seed"; break;
                case chuck: qDebug() << "chuck"; break;
                case hobo: qDebug() << "hobo"; break;
                default: return;
                }
        }
};

/* Good */
class Convenience : public QObject
{
        Q_OBJECT
public:
        enum Store
        {
                None  = 0,
                Sneed = 1 << 0 ,
                Feed  = 1 << 1 ,
                Seed  = 1 << 2 ,
                Chuck = 1 << 3 ,
                Hobo  = 1 << 4 ,
        }; Q_ENUM(Store)
        static const inline QMetaEnum s_MetaStore{ QMetaEnum::fromType<Store>() };

        Convenience( Store store )
        {
                qDebug() << s_MetaStore.valueToKey(store);
        }
};

inline ^§

Encouraged for static member initialization.
Otherwise discouraged.


class Sneed
{
        /* Bad */
        static bool s_Hobo;

        /* Good */
        static const  bool s_Seed{true};
        static inline bool s_Feed{true};
};

unsigned ^§

Never use this keyword.
prefer Qt's typedefs.
Prefer signed integers, because -1 can be used to represent a special value:


if ( this->trySneed(60) ) { ... } // wait one minute
if ( this->trySneed(-1) ) { ... } // wait forever
if ( this->trySneed( 0) ) { ... } // Do not wait at all

long short signed ^§

Always use Qt's typedefs.


class Sneed
{
        /* Bad */
        unsigned char m_uchar;
        signed   char m_char;

        short          m_16 ;
        long long int  m_64 ;

        unsigned char  m_u8 ;
        unsigned short m_u16;
        unsigned int   m_u32;
        unsigned long  m_u64;

        float          m_float ;
        double         m_double;

        /* fine */
        int m_int;

        /* Good */
        uchar   m_uchar;
        qint8   m_char ;

        qint8   m_8   ;
        qint16  m_16  ;
        qint32  m_32  ;
        qint64  m_64  ;

        quint8  m_u8  ;
        quint16 m_u16 ;
        quint32 m_u32 ;
        quint64 m_u64 ;

        qreal   m_real;
};

operator ^§

Freely use if strictly internal.
Discouraged for higher level classes.
Cation: public: overloads catch developers off guard and can mislead.

register ^§

The keyword is unused and reserved since c++ 17.
Never use it.

static ^§

Inline static member variables if possible so their initial value is visible in the header.
Prefix all static variable names with s_.

template ^§

Absolutely fine to use, for both class and methods.
Use of auto is only encouraged if it helps deduce a produced type.
Aim for simplicity.
Difficult to read templates are to be scrapped or rewritten.
Type parameters are named `T`.
If context can be added, or there are multiple parameters, then use `T_` as a prefix like so:


/* Good */
template<typename T_Enum, typename T_Key, typename T_Value>
class QDatabase
{
public:
        explicit QDatabase( const QString &applicationName, const SQL_Metadata options = SQL_Metadata(0) )
                : m_ApplicationName( applicationName )
                , d_Database( QDir::home().absoluteFilePath( ".local/share/qdatabase/" + applicationName ) )
                , m_FileName( d_Database.absoluteFilePath(
                                          this->demangle( typeid(T_Key  ).name() )
                                        + QString(".")
                                        + this->demangle( typeid(T_Value).name() )
                                        + mn_Mime ) )

                , m_Metadata( options )
        {
                Q_ASSERT( QSqlDatabase::isDriverAvailable( mn_Driver ) );
                Q_ASSERT( s_MetaEnum.keyCount() != 0 );
                this->init();

                for ( int i = 0; i < s_MetaEnum.keyCount(); i++ ) {
                        m_ColumnNames.append( s_MetaEnum.key(i) );
                }

        }

        /* [ etc... ] */

}

mutable ^§

Apply to all mutexes.

virtual ^§

Use only when you want to bind developers to certain behaviour.
Required for interfaces and factories.
Useful for plugins.

typedef|using ^§

Prefer using.
Only use typedef for simple types.
Employ when a type differs based on the platform it is compiled on.
Name descriptively.


template<typename T>
class Sneed
{
        /* Bad */
        typedef QList<T> seed;
        typedef void (*feed)();

        /* Fine */
        typedef unsigned long long quint64;
        using quint64 = unsigned long long;

        /* Good */
        using seed = QList<T>;
        using feed = void (*)();

        template <typename T_Feed, typename T_Seed> using Chuck = QPair<T_Feed,T_Seed>;
};

volatile ^§

Use when it is imperative that the compiler should make absolutely no assumptions about this member.
Always apply when reading a spot that a different thread, device, or process might write to.


			|
			Home
			|
			About
			|
			Contact
			|