Library guidelines

[Thiago Macieira]

Olivier Goffart wrote:
>Hello.
>
>Here is a second version of the library guidelines document.
>I think i have taken in accounts most of the hints you gave me.
>
>Thanks to Matt to help me with the English
>
>
>Is there still something to add or modify ?

Actually, I do.

>If all is OK, can someone with karma upload it in developer.kde.org ?

You've got the privileges to do that. Choose a spot in there, probably 
alongside the C++ binary compatibility guide.

Anyways, my comments:

>In KDE, we follow the same naming conventions as Qt, with a few
> exceptions.

Which exceptions? Is that the Q -> K and namespacing rules?

>The prefix 'set' is used for setters, but the prefix 'get' is not used
> for accessors. Accessors are simply named with the name of the property
> they access. The exception is for accessors of a boolean which may
> start with the prefix 'is'.

I'd like to ask that people consider using Q_PROPERTY too for their 
properties. It should not be mandatory, though. The reason for that is 
that properties -- especially properties marked SCRIPTABLE -- will be 
accessible through our future JavaScript interface.

This in turn has an advantage: if you follow 
the "propname" / "setPropname" guideline, moc sets a special flag for the 
QMetaProperty.

> private slots may start with the prefix slot but it's not required

If it's optional, why include this line?

>By convention, the private class will be called Private and will be in
> the class definition.

I'd like to ask that that be scrapped. The guideline should be:
"By convention, the private class will be named the same as the public 
class, with "Private" appended to the name. It must not be a nested 
class."

Why? Because if you do this:
class KDECORE_EXPORT KMyClass
{
  class Private;
  Private * const d;
...
};

then KMyClass::Private is exported too, which is something we'd like to 
avoid.

Besides, if we use something like QObjectPrivate, we could use the 
Q_DECLARE_PUBLIC, Q_DECLARE_PRIVATE, Q_D and Q_Q macros.

>If you are implementing an implicitly shared class, you should consider
> using QSharedData and QSharedDataPointer for d. Use QAtomic for
> reference counting. Don't try to implement your own refcounting with
> integers.

Please invert the two sentences in the paragraph or separate into two 
paragraphs. It gives the impression that you should use QAtomic with 
QSharedData, which you should not do: QSharedData already ref-counts for 
you.

In the "Static objects", I'd like to add:
"Try to avoid creating static arrays of strings because they incur in 
extra relocation at load-time. Example of code to avoid:

static const char *messages[] = {
  "message1",
  "message2",
  0
};

This type of coding should be avoided if possible. The example above could 
be replaced by a list built at first use (in which case you could use a 
QList<QByteArray> too) or by a switch.

However, it is preferred to use this practice if the alternative is code 
that is of difficult readability and/or maintenance."

The section "Signals and slots" could be changed to "Header cleanliness" 
or something similar, and add the following text:

"Installed headers should compile with the following preprocessor defines:
  - QT_NO_CAST_FROM_ASCII
  - QT_NO_CAST_TO_ASCII
  - QT_NO_KEYWORDS"
-- 
Thiago Macieira  -  thiago (AT) macieira.info - thiago (AT) kde.org
  thiago.macieira (AT) trolltech.com     Trolltech AS
    GPG: 0x6EF45358                   |  Sandakerveien 116,
    E067 918B B660 DBD1 105C          |  NO-0402
    966C 33F5 F005 6EF4 5358          |  Oslo, Norway
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 191 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20060316/08cb3689/attachment.sig>