Archive:Development/Tutorials/Common Programming Mistakes (zh TW)

摘要

本教學的目的是結合 KDE 開發者的經驗，關於 Qt 和 KDE 框架該做什麼和什麼不該做。除了實際的錯誤，還包括不一定是「bug」的東西，但會使程式碼變慢或缺乏可讀性。

一般的 C++

本節將指導您一些 C++ 中積灰塵的角落，這些往往被濫用，或是人們常常出錯的地方。

Anonymous namespaces vs 靜態（static）

如果你有一個類別的方法，不存取任何成員，因此並不需要物件來操作；使他成為靜態。如果他還是私有（private）函式，那麼在檔案之外就不需要他；使其成為一個靜態檔案（file-static）函式。這將完全隱藏 symbol。

定義在 C++ 的 anonymous namespace 中的 Symbols，不具有內在聯繫。anonymous namespace只提供一個唯一的名稱給翻譯單位和本身，他們不改變 symbol 的聯繫。那些聯繫是沒有改變的，因為第二階段的名稱查找會忽略函式的內在聯繫。此外，實體的內部聯繫不能作為範本（Template）參數。

So for now instead of using anonymous namespaces use static if you do not want a symbol to be exported.

空指標（null pointer）問題

首先最重要的一點：刪除空指標是沒有影響的。所以，刪除之前檢查是否為空是多餘的：

if ( ptr ) {
   delete ptr;
}

Note however, that a null check is required when you delete an array - that's because a relatively recent compiler on Solaris does not handle it properly otherwise.

當你刪除指標後，一定要還設定為0，這樣將來嘗試刪除物件不會因為雙重刪除而失敗。因此，完整和正確的寫法是：

delete ptr; 
ptr = 0;

您可能會注意到空指標有三種標記方法：0、0L 和 NULL。在C中，NULL 定義為一個null void指標。然而，在C++，由於嚴格的類型檢查，這是不可能的。因此，現代C++實作定義它為「magic」空指標常量（null pointer constant），任何指標都可以指定成它。舊的 C++ 實作，另一方面來說，簡單定義它為0L或0，而沒有提供額外的類型安全 - 人們可以指定它為整數變數，這顯然是錯的。

在指標背景方面，整數常數零意思是｢空指標｣ - 空指標的實際二進位表示法。這意味著選擇0、0L和NULL是一個個人風格和習慣的問題，而不是技術性的。就 KDE SVN 中的程式碼而言，你會看到使用0比NULL更普遍。

但是請注意，如果你想傳遞一個空指標常量給變數參數列表中的一個函數，你必須顯式轉換它為指標 - 編譯器預設情況下假定為整數，可能符合或不符合指標的二進位表示法。同樣的，不論你用0、0L 或 NULL 都沒關係，通常比較喜歡用較短的表示法。

成員變數

在 KDE 中除了未標記的成員，你會遇到四種主要的類別成員變數標記風格：

• m_variable 小寫m、底線和以小寫字母開始的變數名稱。這是最常見的風格和 kdelibs 中偏好的程式碼風格。
• mVariable 小寫 m 和以大寫字母開始的變數名稱。
• variable_ 以小寫字母開始的變數名稱，然後一個底線。
• _variable 底線和以小寫字母開始的變數名稱。這種風格通常是令人難以接受的，因為這種標記也用在一些代替函數參數的程式碼。

未標記成員常見於使用 d-pointers 的類別。

由於沒有一個正確的做法，所以記得要遵循您正在提交的應用程式或函式庫，使用的語法。如果要建立一個新檔案，您可能需要遵循，您要加入檔案的函式庫或模塊的程式碼風格。

請注意，底線符號開始是保留給 C 函式庫（底線加上大寫或雙底線是保留給編譯器），所以如果可以的話，請避免使用上述的類型。

靜態變數

嘗試減少靜態變數的使用量，尤其是當提交給函式庫時。建構和大量靜態變數初始化會嚴重增加啟動時間。

不要使用靜態類別（class-static）變數，尤其是函式庫和可裝入模塊。即使在應用程式也是不鼓勵使用。靜態物件會導致很多問題，如由於未定義建構或解構的次序，難以對 crashes 進行除錯。

相反地，請使用靜態指標，連同 kglobal.h 中定義的 K_GLOBAL_STATIC 一起使用：

class A { ... };

K_GLOBAL_STATIC(A, globalA)

void doSomething()
{
     A *a = globalA;
     ...
}

void doSomethingElse()
{
    if (globalA.isDestroyed()) {
        return;
    }
    A *a = globalA;
    ...
}

void installPostRoutine()
{
    qAddPostRoutine(globalA.destroy);
}

請參閱 K_GLOBAL_STATIC 的API 文件了解更多資訊。

常量（Constant）資料

如果你在幾個地方需要一些簡單資料類型的常量資料。你最好在一個集中的地方只定義它們一次，以避免mistype，在其中一個實例（instance）。如果資料改變也只需要修改一個地方。

即使只有一個實例，你最好還是定義在其他地方，以避免程式碼有所謂的｢magic numbers｣，這是無法解釋（cmp. 42）。通常是放在檔案的頂部，以避免要搜尋它。

定義常量資料請使用C++的語言結構，而不用前置處理器（preprocessor）指令，就像你使用單純的C。這樣編譯器可以透過類型檢查幫助你找到錯誤。

// 正確！
static const int AnswerToAllQuestions = 42;
// 錯誤！
#define AnswerToAllQuestions 42

如果定義了一個常量陣列（Array）不要使用指標的作為資料型態。而是使用資料型態和未定義長度附加陣列符號，[]，在名稱的後面。否則，你還可以定義變數在一些常量資料。這些變數可能錯誤地被指定為新的指標，而編譯器不會出現錯誤。存取陣列應該要有一個間接，因為第一次的變數值需要被讀取。

// 正確！
static const char SomeString[] = "Example";
// 錯誤！
static const char* SomeString = "Example";
// 錯誤！
#define SomeString "Example"

提前宣告

提前宣告類別，而不是含入他們各自的標頭檔，可以減少編譯時間。例如：

#include <QWidget>     // 慢
#include <QStringList> // 慢
#include <QString>     // 慢
class SomeInterface
{
public:
    virtual void widgetAction( QWidget *widget ) =0;
    virtual void stringAction( const QString& str ) =0;
    virtual void stringListAction( const QStringList& strList ) =0;
};

上述內容應當改成這樣寫：

class QWidget;     // 快
class QStringList; // 快
class QString;     // 快
class SomeInterface
{
public:
    virtual void widgetAction( QWidget *widget ) =0;
    virtual void stringAction( const QString& str ) =0;
    virtual void stringListAction( const QStringList& strList ) =0;
};

迭代器

Prefer const iterators and cache end()

Prefer to use const_iterators over normal iterators when possible. Containers, which are being implicitly shared often detach when a call to a non-const begin() or end() methods is made (QList is an example of such a container). When using a const_iterator also watch out that you are really calling the const version of begin() and end(). Unless your container is actually const itself this probably will not be the case, possibly causing an unnecessary detach of your container. So basically whenever you use const_iterator initialize them using constBegin()/constEnd() instead, to be on the safe side.

Cache the return of the end() (or constEnd()) method call before doing iteration over large containers. For example:

QList<SomeClass> container;

//code which inserts a large number of elements to the container

QList<SomeClass>::ConstIterator end = container.constEnd();
QList<SomeClass>::ConstIterator itr = container.constBegin();

for ( ; itr != end; ++itr ) {
    // use *itr (or itr.value()) here
}

This avoids the unnecessary creation of the temporary end() (or constEnd()) return object on each loop iteration, largely speeding it up.

When using iterators, always use pre-increment and pre-decrement operators (i.e., ++itr) unless you have a specific reason not to. The use of post-increment and post-decrement operators (i.e., itr++) cause the creation of a temporary object.

Take care when erasing elements inside a loop

When you want to erase some elements from the list, you maybe would use code similar to this:

QMap<int, Job *>::iterator it = m_activeTimers.begin();
QMap<int, Job *>::iterator itEnd = m_activeTimers.end();

for( ; it != itEnd ; ++it) {
    if(it.value() == job) {
        //A timer for this job has been found. Let's stop it.
        killTimer(it.key());
        m_activeTimers.erase(it);
    }
}

This code will potentially crash because it is a dangling iterator after the call to erase(). You have to rewrite the code this way:

QMap<int, Job *>::iterator it = m_activeTimers.begin();
while (it != m_activeTimers.end()) {
    if(it.value() == job) {
        //A timer for this job has been found. Let's stop it.
        killTimer(it.key());
        it = m_activeTimers.erase(it);
    } else {
        ++it;
    }
}

This problem is also discussed in the Qt documentation for QMap::iterator but applies to all Qt iterators

記憶體洩漏

一個非常「常犯」的程式設計錯誤是實做 new 而沒有 delete，就這個程式一樣：

mem_gourmet.cpp

class t
{
  public:
    t() {}
};

void pollute()
{
  t* polluter = new t();
}

int main()
{
  while (true) pollute();
}

你看，pollute()建立一個新的物件，t類別的polluter。然後，polluter　變數丟失，因為它是區域（local）的，但其內容（物件）仍留在 heap 中。我可以使用這個程式讓電腦在10秒內無法使用。

為了解決這個問題，有以下方法：

• 保持變數在 stack 而不是 heap：

  t* polluter = new t();

改為

 
  t polluter;

• 刪除polluter，使用 new 的補充函式：

 
  delete polluter;

• 用std::auto_ptr 停止 polluter（這在從該方法返回時，將自動刪除 polluter）

 std::auto_ptr<t> polluter = new t();

Valgrind之類的工具可以檢測記憶體洩漏。

dynamic_cast

You can only dynamic_cast to type T from type T2 provided that:

• T is defined in a library you link to (you'd get a linker error if this isn't the case, since it won't find the vtable or RTTI info)
• T is "well-anchored" in that library. By "well-anchored" I mean that the vtable is not a COMMON symbol subject to merging at run-time by the dynamic linker. In other words, the first virtual member in the class definition must exist and not be inlined: it must be in a .cpp file.
• T and T2 are exported

For instance, we've seen some hard-to-track problems in non-KDE C++ code we're linking with (I think NMM) because of that. It happened that:

• libphonon loads the NMM plugin
• NMM plugin links to NMM
• NMM loads its own plugins
• NMM's own plugins link to NMM

Some classes in the NMM library did not have well-anchored vtables, so dynamic_casting failed inside the Phonon NMM plugin for objects created in the NMM's own plugins.

程式設計

在本節中，我們將繼續與 Qt/KDE 應用程式設計相關的常見問題。

延遲初始化（delayed initialization）

儘管設計現代 C++ 應用程式可能會非常複雜。一個反覆出現的問題，通常是很容易解決的。是沒有使用延遲初始化的技術。

首先，讓我們看看初始化 KDE 應用程式的標準方式：

int main( int argc, char **argv )
{
    ....
    KApplication a;

    KCmdLineArgs *args = KCmdLineArgs::parsedArgs();

    MainWindow *window = new MainWindow( args );

    a.setMainWidget( window );
    window->show();

    return a.exec();
}

Notice that window is created before the a.exec() call that starts the event loop. This implies that we want to avoid doing anything non-trivial in the top-level constructor, since it runs before we can even show the window.

The solution is simple: we need to delay the construction of anything besides the GUI until after the event loop has started. Here is how the example class MainWindow's constructor could look to achieve this:

MainWindow::MainWindow()
{
    initGUI();
    QTimer::singleShot( 0, this, SLOT(initObject()) );
}

void MainWindow::initGUI()
{
    /* Construct your widgets here.  Note that the widgets you
     * construct here shouldn't require complex initialization
     * either, or you've defeated the purpose.
     * All you want to do is create your GUI objects and
     * QObject::connect
     * the appropriate signals to their slots.
     */
}

void MainWindow::initObject()
{
    /* This slot will be called as soon as the event loop starts.
     * Put everything else that needs to be done, including
     * restoring values, reading files, session restoring, etc here.
     * It will still take time, but at least your window will be
     * on the screen, making your app look active.
     */
}

Using this technique may not buy you any overall time, but it makes your app seem quicker to the user who is starting it. This increased perceived responsiveness is reassuring for the user as they get quick feedback that the action of launching the app has succeeded.

When (and only when) the start up can not be made reasonably fast enough, consider using a KSplashScreen.

資料結構

在本節中，我們會繼續一些最常見的 pet-peeves，在 Qt/KDE 應用程式中影響資料結構非常常見。

Passing non-POD types

Non-POD ("plain old data") types should be passed by const reference if at all possible. This includes anything other than the basic types such as char and int.

Take, for instance, QString. They should always be passed into methods as const QString&. Even though QString is implicitly shared it is still more efficient (and safer) to pass const references as opposed to objects by value.

So the canonical signature of a method taking QString arguments is:

void myMethod( const QString & foo, const QString & bar );

QObject

If you ever need to delete a QObject derived class from within one of its own methods, do not ever delete it this way:

   delete this;

This will sooner or later cause a crash because a method on that object might be invoked from the Qt event loop via slots/signals after you deleted it.

Instead always use QObject::deleteLater() which tries to do the same thing as delete this but in a safer way.

空 QStrings

It is common to want to see if a QString is empty. Here are three ways of doing it, the first two of which are correct:

// Correct
if ( mystring.isEmpty() ) {
}

// Correct
if ( mystring == QString() ) {
}

// Wrong! ""
if ( mystring == "" ) {
}

While there is a distinction between "null" QStrings and empty ones, this is a purely historical artifact and new code is discouraged from making use of it.

QString 和讀取檔案

If you are reading in a file, it is faster to convert it from the local encoding to Unicode (QString) in one go, rather than line by line. This means that methods like QIODevice::readAll() are often a good solution, followed by a single QString instantiation.

For larger files, consider reading a block of lines and then performing the conversion. That way you get the opportunity to update your GUI. This can be accomplished by reentering the event loop normally, along with using a timer to read in the blocks in the background, or by creating a local event loop.

While one can also use qApp->processEvents(), it is discouraged as it easily leads to subtle yet often fatal problems.

Reading QString from a KProcess

KProcess emits the signals readyReadStandard{Output|Error} as data comes in. A common mistake is reading all available data in the connected slot and converting it to QString right away: the data comes in arbitrarily segmented chunks, so multi-byte characters might be cut into pieces and thus invalidated. Several approaches to this problem exist:

• Do you really need to process the data as it comes in? If not, just use readAllStandard{Output|Error} after the process has exited. Unlike in KDE3, KProcess is now able to accumulate the data for you.
• Wrap the process into a QTextStream and read line-wise. This should work starting with Qt 4.4.
• Accumulate data chunks in the slots and process them each time a newline arrives or after some timeout passes. Example code

QString 和 QByteArray

While QString is the tool of choice for many string handling situations, there is one where it is particularly inefficient. If you are pushing about and working on data in QByteArrays, take care not to pass it through methods which take QString parameters; then make QByteArrays from them again.

For example:

QByteArray myData;
QString myNewData = mangleData( myData );

QString mangleData( const QString& data ) {
    QByteArray str = data.toLatin1();
    // mangle 
    return QString(str);
}

The expensive thing happening here is the conversion to QString, which does a conversion to Unicode internally. This is unnecessary because, the first thing the method does is convert it back using toLatin1(). So if you are sure that the Unicode conversion is not needed, try to avoid inadvertently using QString along the way.

The above example should instead be written as:

QByteArray myData;
QByteArray myNewData = mangleData( myData );

QByteArray mangleData( const QByteArray& data )

QDomElement

When parsing XML documents, one often needs to iterate over all the elements. You may be tempted to use the following code for that:

for ( QDomElement e = baseElement.firstChild().toElement();
      !e.isNull();
      e = e.nextSibling().toElement() ) {
       ...
}

That is not correct though: the above loop will stop prematurely when it encounters a QDomNode that is something other than an element such as a comment.

The correct loop looks like:

for ( QDomNode n = baseElement.firstChild(); !n.isNull();
      n = n.nextSibling() ) {
    QDomElement e = n.toElement();
    if ( e.isNull() ) {
        continue;
    }
    ...
}