[QGIS Commit] r9647 - in trunk/qgis: . doc

[svn_qgis at osgeo.org]

Author: timlinux
Date: 2008-11-16 17:28:51 -0500 (Sun, 16 Nov 2008)
New Revision: 9647

Modified:
   trunk/qgis/CODING
   trunk/qgis/doc/CODING.t2t
Log:
Added some notes about API compatibility

Modified: trunk/qgis/CODING
===================================================================
--- trunk/qgis/CODING	2008-11-16 15:16:39 UTC (rev 9646)
+++ trunk/qgis/CODING	2008-11-16 22:28:51 UTC (rev 9647)
@@ -24,13 +24,14 @@
       1.7.1. Tabs
       1.7.2. Indentation
       1.7.3. Braces
-    1.8. Coding Style
-      1.8.1. Where-ever Possible Generalize Code
-      1.8.2. Prefer Having Constants First in Predicates
-      1.8.3. Whitespace Can Be Your Friend
-      1.8.4. Add Trailing Identifying Comments
-      1.8.5. Use Braces Even for Single Line Statements
-      1.8.6. Book recommendations
+    1.8. API Compatibility
+    1.9. Coding Style
+      1.9.1. Where-ever Possible Generalize Code
+      1.9.2. Prefer Having Constants First in Predicates
+      1.9.3. Whitespace Can Be Your Friend
+      1.9.4. Add Trailing Identifying Comments
+      1.9.5. Use Braces Even for Single Line Statements
+      1.9.6. Book recommendations
   2. SVN Access
     2.1. Accessing the Repository
     2.2. Anonymous Access
@@ -273,13 +274,41 @@
 
 
 
-	1.8. Coding Style
+	1.8. API Compatibility
+	======================
+
+From QGIS 1.0 we will provide a stable, backwards compatible API. This will
+provide a stable basis for people to develop against, knowing their code will
+work against any of the 1.x QGIS releases (although recompiling may be
+required).Cleanups to the API should be done in a manner similar to the
+Trolltech developers e.g.
+
+
+  class Foo 
+  {
+    public:
+      /** This method will be deprecated, you are encouraged to use 
+        doSomethingBetter() rather.
+        @see doSomethingBetter()
+       */
+      bool doSomething();
+  
+      /** Does something a better way.
+        @note This method was introduced in QGIS version 1.1
+       */
+      bool doSomethingBetter();
+  
+  }
+
+
+
+	1.9. Coding Style
 	=================
 
 Here are described some programming hints and tips that will hopefully reduce errors, development time, and maintenance.
 
 
-		1.8.1. Where-ever Possible Generalize Code
+		1.9.1. Where-ever Possible Generalize Code
 		==========================================
 
 
@@ -294,7 +323,7 @@
 maintain for others
 
 
-		1.8.2. Prefer Having Constants First in Predicates
+		1.9.2. Prefer Having Constants First in Predicates
 		==================================================
 
 Prefer to put constants first in predicates. 
@@ -308,7 +337,7 @@
 inherently cannot be assigned values.
 
 
-		1.8.3. Whitespace Can Be Your Friend
+		1.9.3. Whitespace Can Be Your Friend
 		====================================
 
 Adding spaces between operators, statements, and functions makes it easier for humans to parse code.
@@ -326,7 +355,7 @@
 
 
 
-		1.8.4. Add Trailing Identifying Comments
+		1.9.4. Add Trailing Identifying Comments
 		========================================
 
 Adding comments at the end of function, struct and class implementations makes it easier to find them later.
@@ -346,7 +375,7 @@
 
 
 
-		1.8.5. Use Braces Even for Single Line Statements
+		1.9.5. Use Braces Even for Single Line Statements
 		=================================================
 
 Using braces for code in if/then blocks or similar code structures even for single line statements means that adding another 
@@ -378,7 +407,7 @@
 
 
 
-		1.8.6. Book recommendations
+		1.9.6. Book recommendations
 		===========================
 
  * Effective C++ (http://www.awprofessional.com/title/0321334876), Scott Meyers
@@ -1234,10 +1263,10 @@
 
  1. Group related elements using group boxes:
    Try to identify elements that can be grouped together and then use 
-   group boxes with a label identify the topic of that group. 
+   group boxes with a label to identify the topic of that group. 
    Avoid using group boxes with only a single widget / item inside.
- 2. Capitalise first letter only in group box labels:
-   Group box labels should be written as a phrase with leading capital letter,
+ 2. Capitalise first letter only in labels:
+   Labels (and group box labels) should be written as a phrase with leading capital letter,
    and all remaing words written with lower case first letters 
  3. Do not end labels for widgets or group boxes with a colon:
    Adding a colon causes visual noise and does not impart additional meaning,

Modified: trunk/qgis/doc/CODING.t2t
===================================================================
--- trunk/qgis/doc/CODING.t2t	2008-11-16 15:16:39 UTC (rev 9646)
+++ trunk/qgis/doc/CODING.t2t	2008-11-16 22:28:51 UTC (rev 9647)
@@ -195,7 +195,34 @@
 	}
 ```
 
+== API Compatibility ==
 
+From QGIS 1.0 we will provide a stable, backwards compatible API. This will
+provide a stable basis for people to develop against, knowing their code will
+work against any of the 1.x QGIS releases (although recompiling may be
+required).Cleanups to the API should be done in a manner similar to the
+Trolltech developers e.g.
+
+
+```
+class Foo 
+{
+  public:
+    /** This method will be deprecated, you are encouraged to use 
+      doSomethingBetter() rather.
+      @see doSomethingBetter()
+     */
+    bool doSomething();
+
+    /** Does something a better way.
+      @note This method was introduced in QGIS version 1.1
+     */
+    bool doSomethingBetter();
+
+}
+```
+
+
 == Coding Style ==
 
 Here are described some programming hints and tips that will hopefully reduce errors, development time, and maintenance.
@@ -1108,10 +1135,10 @@
 
  + Group related elements using group boxes:
    Try to identify elements that can be grouped together and then use 
-   group boxes with a label identify the topic of that group. 
+   group boxes with a label to identify the topic of that group. 
    Avoid using group boxes with only a single widget / item inside.
- + Capitalise first letter only in group box labels:
-   Group box labels should be written as a phrase with leading capital letter,
+ + Capitalise first letter only in labels:
+   Labels (and group box labels) should be written as a phrase with leading capital letter,
    and all remaing words written with lower case first letters 
  + Do not end labels for widgets or group boxes with a colon:
    Adding a colon causes visual noise and does not impart additional meaning,