DRAFT document on coding conventions in kde libraries

[Friedrich W. H. Kossebau]

> Am Montag, 6. März 2006 01:10, schrieb David Faure:
> > > See, it seems not to be used in Qt itself, either!
> >
> > I agree that it's not widely used in Qt, but still:
> > ./network/qhttp.cpp:85:    // private slots
> > ./network/qhttp.cpp:87:    void slotReadyRead();
> > ./network/qhttp.cpp:88:    void slotConnected();
> > ./network/qhttp.cpp:89:    void slotError(QAbstractSocket::SocketError);
> > ./network/qhttp.cpp:90:    void slotClosed();
> > ./network/qhttp.cpp:91:    void slotBytesWritten(qint64 numBytes);
> > ./network/qhttp.cpp:92:    void slotDoFinished();
> >
> > See, connected() would look like a method that returns a boolean telling
> > the caller whether we are connected. On the other hand slotConnected()
> > tells me right away that this is the slot connected (no pun intended!) to
> > the connected signal. Same thing with closed() vs slotClosed().

Still can't get away from it:
So these are methods only to be triggered by observed objects with the given 
signals. Because otherwise we would not know that we need the slot and would 
not have done the naming as it only refers to the signal, not the method's 
effect. Right? All we know by the name is that the method deals with those 
signals, not what it really does. The method is all about the signal, then. 
Hm. Okay. So it really can only be "called" by the signal as no other 
contract is given. Even the connector does not know what the observer does 
unless it's the observer himself. Calling such slots directly would hurt the 
contract as it would destroy the pattern and result in undefined reactions.

I think I see, so I'm in. Or did I miss something?

Okay. So what about this? 
A special prefix only for methods who are exclusively to be triggered on 
signals with a given semantic x. All other slottable functions without 
prefix. To make the concept clear (and to become consistent with other 
languages) the prefix should be "on", followed by the semantic description. 

Taking your example:
./network/qhttp.cpp:85:    // private slots
./network/qhttp.cpp:87:    void onReadyRead();
./network/qhttp.cpp:88:    void onConnected();
./network/qhttp.cpp:89:    void onError(QAbstractSocket::SocketError);
./network/qhttp.cpp:90:    void onClosed();
./network/qhttp.cpp:91:    void onBytesWritten(qint64 numBytes);
And (the original name suggests this, might serve both as slot and as plain 
method):
./network/qhttp.cpp:92:    void doFinished();

This would make much sense to me and help with both using the methods and 
reading the code, wouldn't it? Please take this idea into account. 

Using "slot" as prefix might "discriminate" the semislots. Oh, no, I do _not_ 
propose now to prefix those with "semislot"! #)

Too sad it could not be incorporated by Qt now. Because, after all it would be 
best to have the same conventions as Qt because most of KDE applications will 
use KDE and Qt libraries intermixed. But then we are KDE, not QDE :P
And perhaps there are no such for-signal-x-only methods in the public 
interface? (If so, why?)

Well, inner problem solved, now I can sleep :) (only kidding)

Regards
Friedrich
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20060306/45ae0266/attachment.sig>