Policies/Library Code Policy - Revision history

Mck182: Add note about QScopedPointer for d-pointers

2013-01-07T08:07:35Z

Add note about QScopedPointer for d-pointers

Sandsmark: gotcha for qshareddata

2012-12-17T13:09:21Z

gotcha for qshareddata

Jstaniek: update link to http://wiki.qt-project.org/index.php?title=API_Design_Principles

2012-12-05T19:51:13Z

update link to http://wiki.qt-project.org/index.php?title=API_Design_Principles

Ogoffart: /* D-Pointers */ Use smart pointer.

2012-02-17T12:51:13Z

‎D-Pointers: Use smart pointer.

Jstaniek at 20:12, 21 November 2011

2011-11-21T20:12:13Z

ORBAT: Changed all `tags to tags to fix syntax highlighting problems + changed two angle brackets to HTML entities`


2011-06-28T08:41:42Z
Changed all <code> tags to <source> tags to fix syntax highlighting problems + changed two angle brackets to HTML entities
Show changes



Aseigo: /* Documentation */
2010-08-10T20:32:07Z
‎Documentation

				
				
				
				
			
			← Older revision
			Revision as of 20:32, 10 August 2010
			
Line 357:
Line 357:
  '''Note''': If you are unsure about the normalization, don't do it. Let   '''Note''': If you are unsure about the normalization, don't do it. Let
  QObject do it for you (the performance penalty is negligible in most cases).   QObject do it for you (the performance penalty is negligible in most cases).
  + 
  + == External Dependencies ==
  + When a library pulls in a new external dependency due to a new feature or a change in implementation, it is highly preferred to make that dependency optional if at all possible. For some core features in a library this may not be possible, but usually it is even if the cost is a degradation in features when built without that dependency.
  + 
  + All dependencies should be adequately documented in the build system so that they appear in the summary post-configure.
  + 
  + For libraries in the '''kdelibs module''', this is a hard requirement: '''no new non-optional dependencies may be added, all new dependencies must be made optional at configure time'''. Exceptions may be granted for unusual circumstances by sending a request to the kde-core-devel at kde.org mailing list and getting a consensus decision to grant an exception there.
    
  == Documentation ==   == Documentation ==





Dhaumann: use full qualified name for namespaced types
2009-01-15T13:22:22Z
use full qualified name for namespaced types

				
				
				
				
			
			← Older revision
			Revision as of 13:22, 15 January 2009
			
Line 343:
Line 343:
  It would be preferable to write as follows:   It would be preferable to write as follows:
  <code cppqt>   <code cppqt>
− QObject::connect(this, SIGNAL(newValue(QString,Type)), + QObject::connect(this, SIGNAL(newValue(QString,MyNamespace::Type)),
                    other, SLOT(value(QString)));                     other, SLOT(value(QString)));
  </code>   </code>
    
− Note the absence of namespace markers, extra whitespace and the + Note the absence of extra whitespace and the
  reduction of pass-by-reference-to-const parameters to simple   reduction of pass-by-reference-to-const parameters to simple
  pass-by-value ones. The normalization may involve other   pass-by-value ones. The normalization may involve other
− transformations, but these are the most common ones. To be sure what + transformations, but these are the most common ones. Also note that
− the proper normalization is, read the {{path|.moc}} file generated + types in namespaces should always use the full qualified name.
− for the class. + To be sure what the proper normalization is, read the {{path|.moc}} file
  + generated for the class.
    
  '''Note''': If you are unsure about the normalization, don't do it. Let   '''Note''': If you are unsure about the normalization, don't do it. Let





Dhaumann: /* Inline Code */
2008-10-28T15:28:42Z
‎Inline Code

				
				
				
				
			
			← Older revision
			Revision as of 15:28, 28 October 2008
			
Line 113:
Line 113:
  * Installed headers should compile with the following preprocessor defines: <tt>QT_NO_CAST_FROM_ASCII</tt>, <tt>QT_NO_CAST_TO_ASCII</tt>, <tt>QT_NO_KEYWORD</tt>. So don't forget {{qt|QLatin1String}}.   * Installed headers should compile with the following preprocessor defines: <tt>QT_NO_CAST_FROM_ASCII</tt>, <tt>QT_NO_CAST_TO_ASCII</tt>, <tt>QT_NO_KEYWORD</tt>. So don't forget {{qt|QLatin1String}}.
  * No C casts in the header. Use <tt>static_cast</tt> if types are known. Use <tt>qobject_cast</tt> instead of <tt>dynamic_cast</tt> if types are QObject based. dynamic_cast is not only slower, but is also unreliable across shared libraries.   * No C casts in the header. Use <tt>static_cast</tt> if types are known. Use <tt>qobject_cast</tt> instead of <tt>dynamic_cast</tt> if types are QObject based. dynamic_cast is not only slower, but is also unreliable across shared libraries.
− * In general, check your code for [Development/Tutorials/Common_Programming_Mistakes|common mistakes]. + * In general, check your code for [[Development/Tutorials/Common_Programming_Mistakes|common mistakes]].
    
  These recommendations are also true for code that are not in headers.   These recommendations are also true for code that are not in headers.





Dhaumann: use techbase page
2008-10-28T15:28:23Z
use techbase page

				
				
				
				
			
			← Older revision
			Revision as of 15:28, 28 October 2008
			
Line 113:
Line 113:
  * Installed headers should compile with the following preprocessor defines: <tt>QT_NO_CAST_FROM_ASCII</tt>, <tt>QT_NO_CAST_TO_ASCII</tt>, <tt>QT_NO_KEYWORD</tt>. So don't forget {{qt|QLatin1String}}.   * Installed headers should compile with the following preprocessor defines: <tt>QT_NO_CAST_FROM_ASCII</tt>, <tt>QT_NO_CAST_TO_ASCII</tt>, <tt>QT_NO_KEYWORD</tt>. So don't forget {{qt|QLatin1String}}.
  * No C casts in the header. Use <tt>static_cast</tt> if types are known. Use <tt>qobject_cast</tt> instead of <tt>dynamic_cast</tt> if types are QObject based. dynamic_cast is not only slower, but is also unreliable across shared libraries.   * No C casts in the header. Use <tt>static_cast</tt> if types are known. Use <tt>qobject_cast</tt> instead of <tt>dynamic_cast</tt> if types are QObject based. dynamic_cast is not only slower, but is also unreliable across shared libraries.
− * In general, check your code for [http://developer.kde.org/documentation/other/mistakes.html common mistakes]. + * In general, check your code for [Development/Tutorials/Common_Programming_Mistakes|common mistakes].
    
  These recommendations are also true for code that are not in headers.   These recommendations are also true for code that are not in headers.

@@ Line 67: / Line 67: @@
+}
 </source>
-Notice that the member d is <tt>const</tt> to avoid modifying it by mistake.
+Notice that the member d is <tt>const</tt> to avoid modifying it by mistake. This example also uses {{qt|QScopedPointer}} for the d-pointer. It's not a requirement, you can use just your private class directly, but then you need to take care of deleting it properly in the destructor. {{qt|QScopedPointer}} does that for you automatically, see the docs for more details.
 If you are implementing an implicitly shared class, you should consider using {{qt|QSharedData}} and {{qt|QSharedDataPointer}} for d. if you do, remember you need to implement explicit constructors, destructors and assignment operators (operator=).

@@ Line 69: / Line 69: @@
 Notice that the member d is <tt>const</tt> to avoid modifying it by mistake.
-If you are implementing an implicitly shared class, you should consider using {{qt|QSharedData}} and {{qt|QSharedDataPointer}} for d.
+If you are implementing an implicitly shared class, you should consider using {{qt|QSharedData}} and {{qt|QSharedDataPointer}} for d. if you do, remember you need to implement explicit constructors, destructors and assignment operators (operator=).
 Sometimes, complex code may be moved to a member method of the Private class itself. Doing this may give the compiler an extra register to optimize the code, since you won't be using "d" all the time. Also, remember to '''inline''' such methods if they are called only from one place.

@@ Line 1: / Line 1: @@
 This document describes some of the recommended conventions that should be applied in the KDE libraries (not applications). Respecting these guidelines helps create a consistant API and also may help ease maintainence of the libraries later. While these conventions are not mandatory, they are important guidelines, and should be respected unless you have a good reason to disregard them.
-As an introduction, you should read the document [http://wiki.qt-project.org/API_Design_Principles Qt-Style C++ API Design Principles].
+As an introduction, you should read the document [http://wiki.qt-project.org/index.php?title=API_Design_Principles Qt-Style C++ API Design Principles].
 For kdelibs, it is recommended to follow the [[Policies/Kdelibs_Coding_Style | Kdelibs Coding Style]].

@@ Line 44: / Line 44: @@
      /* public members */
 private:
-     KFooPrivate * const d;
+     const QScopedPointer<KFooPrivate> d;
 };
 </source>
@@ Line 61: / Line 61: @@
 KFoo::~KFoo()
-−
+{
-    delete d;
+ // You must define a non-inline destructor in the .cpp file, even if it is empty
+}
 </source>

@@ Line 1: / Line 1: @@
 This document describes some of the recommended conventions that should be applied in the KDE libraries (not applications). Respecting these guidelines helps create a consistant API and also may help ease maintainence of the libraries later. While these conventions are not mandatory, they are important guidelines, and should be respected unless you have a good reason to disregard them.
-As an introduction, you should read the document [http://doc.trolltech.com/qq/qq13-apis.html Designing Qt-Style C++ APIs].
+As an introduction, you should read the document [http://wiki.qt-project.org/API_Design_Principles Qt-Style C++ API Design Principles].
 For kdelibs, it is recommended to follow the [[Policies/Kdelibs_Coding_Style | Kdelibs Coding Style]].

Policies/Library Code Policy - Revision history

Mck182: Add note about QScopedPointer for d-pointers

Sandsmark: gotcha for qshareddata

Jstaniek: update link to http://wiki.qt-project.org/index.php?title=API_Design_Principles

Ogoffart: /* D-Pointers */ Use smart pointer.

Jstaniek at 20:12, 21 November 2011

ORBAT: Changed all tags to tags to fix syntax highlighting problems + changed two angle brackets to HTML entities

Aseigo: /* Documentation */

Dhaumann: use full qualified name for namespaced types

Dhaumann: /* Inline Code */

Dhaumann: use techbase page

ORBAT: Changed all `tags to tags to fix syntax highlighting problems + changed two angle brackets to HTML entities`