Author: dylan
Date: 2005-01-25 18:12:50 -0500 (Tue, 25 Jan 2005)
New Revision: 607
Modified:
trunk/docs/guidelines.txt
Log:
updated guidelines to include new information, and a pointer to perlmodstyle.
Modified: trunk/docs/guidelines.txt
===================================================================
--- trunk/docs/guidelines.txt 2005-01-23 21:45:12 UTC (rev 606)
+++ trunk/docs/guidelines.txt 2005-01-25 23:12:50 UTC (rev 607)
@@ -20,6 +20,8 @@
* Don't use => as a lazy way of quoting things.
GOOD: foo => 'bar', baz => 'quux'
BAD: foo => bar => baz => 'quux' <-- this confuses the hell out of me.
+ * Now it is true that => quotes things with colons in them, vim doesn't
think so...
+ So, for things that don't match /\w+/, quote them.
* POE
* "new" methods must *always* return new objects.
@@ -45,9 +47,12 @@
* Methods
* These should be all lower case, and have meaningful names.
- * For constructors, use the poetic syntax: "new Object".
+ * For constructors, use the poetic syntax: "new Object" (or instance
Object, etc)
* For all other methods, Object->method is preferred.
+* Arguments
+ * Prefer named arguments to positional.
+ * Named arguments should begin with a dash (-) and be all lower case.
* Commenting
* Use tags vim/emacs knows about like FIXME, TODO, and XXX,
@@ -62,12 +67,14 @@
than comments.
* Documentation
+ * Read perldoc perlmodstyle.
+ * Read perldoc perlpod
* Please, please, try to document perl modules with POD.
At least, when a module is in a "usable" state,
it should have documentation.
* Documents should contain NAME, SYNOPSIS, DESCRIPTION, SEE ALSO, AUTHOR,
and COPYRIGHT and LICENSE sections.
- * Additional, optional, sections include EXPORTS (after DESCRIPTION),
INHERITANCE (before METHODS),
+ * Additional, optional, sections include EXPORTS (after FUNCTIONS),
INHERITANCE (before METHODS),
FUNCTIONS and/or METHODS after DESCRIPTION, and perhaps ABSTRACT before
DESCRIPTION,
if DESCRIPTION is somewhat long or complicated.
* Each method or function should be documented in the FUNCTIONS or METHODS
section,
@@ -77,3 +84,5 @@
* If longer cookbook-style examples need to be given, use a
"Module/Name/Cookbook.pod" file
for them. Try to keep SYNOPSIS under 20 lines. This is not a hard limit.
+ * SEE ALSO should contain a link to the haver website, unless it is a
separate project.
+ * BUGS should link to the bug-tracking system on Gna!, unless it is a
separate project.
