[amx-netlinx-common] r43 committed - Edited wiki page CodeFormatAndCommenting through web user interface....

[amx-netli...@googlecode.com]

Revision: 43
Author: jordevorstenbosch
Date: Thu Nov 11 00:44:52 2010
Log: Edited wiki page CodeFormatAndCommenting through web user interface.

Added Commenting guidelines. Fixed a typo.
http://code.google.com/p/amx-netlinx-common/source/detail?r=43

Modified:
/wiki/CodeFormatAndCommenting.wiki

=======================================
--- /wiki/CodeFormatAndCommenting.wiki Sun May 9 18:17:04 2010
+++ /wiki/CodeFormatAndCommenting.wiki Thu Nov 11 00:44:52 2010
@@ -194,7 +194,7 @@
some random integer loop counter, it should be called `i`, or similar.
Calling it `loop_counter` is non-productive, if there is no chance of it
being misunderstood. Similarly, `tmp` can be just about any type of
variable that is used to hold a temporary value.

==Function Parameter Names==
-Sticking with the 'lazy programmer approach' of using short names,
functions in which the argument type is implied (ie. `sqrt()`) should use a
single character variable name - `x`. For functions requiring multiple
arguments, or where the parameter my not by obvious, descriptive names
(which adhere to the above variable naming guidelines) should be utilized.
+Sticking with the 'lazy programmer approach' of using short names,
functions in which the argument type is implied (ie. `sqrt()`) should use a
single character variable name - `x`. For functions requiring multiple
arguments, or where the parameter may not by obvious, descriptive names
(which adhere to the above variable naming guidelines) should be utilized.

==Line Termination==
Although the NetLinx compiler permits the use of a semi-colon (`;`) to
signify line termination this should not be used, as lines are
automatically terminated.
@@ -204,4 +204,33 @@
As revision control is handled by a subversion server, no files committed
to the `/trunk` directory should contain version numbering as a component
of their filename. When milestones are reached or fixes have been made
which warrant an official release, a compressed archive should be created
containing the files involved in the release. This archive can then be
committed to the `/releases` directory in the repository and added to the
project downloads page. The files within these archives should maintain
consistent naming to prevent changes to code which utilize the libraries.

=Commenting=
-Todo: add info on java-doc ish style commenting guidelines.
+Comments are good, but there is also a danger of over-commenting. NEVER
+try to explain HOW your code works in a comment: it's much better to
+write the code so that the _working_ is obvious, and it's a waste of
+time to explain badly written code.
+
+Generally, you want your comments to tell WHAT your code does, not HOW.
+Also, try to avoid putting comments inside a function body: if the
+function is so complex that you need to separately comment parts of it,
+you should probably go back to chapter 6 for a while. You can make
+small comments to note or warn about something particularly clever (or
+ugly), but try to avoid excess. Instead, put the comments at the head
+of the function, telling people what it does, and possibly WHY it does
+it.
+
+The preferred style for long (multi-line) comments is:
+{{{
+/*
+ * This is the preferred style for multi-line
+ * comments.
+ * Please use it consistently.
+ *
+ * Description: A column of asterisks on the left side,
+ * with beginning and ending almost-blank lines.
+ */
+}}}
+
+To save space you can put a comment on one line:
+{{{
+/* This comment takes up only one line. */
+}}}