Migrated from fixing-and-extending-comicpress v9

Fixing-and-Extending-ComicPress.textile

@@ -32,4 +32,40 @@ h2. Producing a patch
 
 If you're using git, "git-format-patch":http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html will do the trick. Bundle up the patch and send it to me.
 
-If you're not using git, send along the modified theme files and I'll do my best to integrate your changes into the theme. Please be specific about what changed in your mail to me.
+If you're not using git, send along the modified theme files and I'll do my best to integrate your changes into the theme. Please be specific about what changed in your mail to me.
+
+h2. Documenting your work
+
+We use "PhpDocumentor":http://www.phpdoc.org/ and "PHPXref":http://phpxref.sourceforge.net/ to automatically generate documentation for the source code. If you're creating new functions or variables, use "JavaDoc-style":http://java.sun.com/j2se/javadoc/writingdoccomments/ comments in your code.
+
+Also, please don't do this:
+<pre>
+// this function does blah
+function my_new_function($param) {
+  // initialize blah
+  $param2 = magic($param);
+  // check the new param to see if it's a number
+  if (is_numeric($param2)) {
+    // make a new number
+    $param3 = more_magic($param2);
+    // print out the number
+    echo $param3;
+  // done
+  }
+// done
+}
+</pre>
+
+Instead, do this:
+
+<pre>
+/**
+ * Print out a magic number.
+ * @param string $initial_string The string we're passing in.
+ */
+function print_magic_number($initial_string) {
+  if (is_numeric($number_version = magic($initial_string))) {
+    echo more_magic($param3);
+  }
+}
+</pre>