Update hacking with some other gotchas

git-svn-id: file:///home/svn/framework3/trunk@12429 4d416f70-5f16-0410-b530-b9f4589650da

HACKING

@@ -15,6 +15,10 @@ adhere to the following style guidelines:
  - do; end instead of {} for a block
  - Always use str[0,1] instead of str[0]
    (This avoids a known ruby 1.8/1.9 incompatability.)
+ - Method names should always be lower_case and words separated by "_"
+ - Variable names should be lower case with words separated by "_"
+ - Don't depend on any external gems or libraries without talking to
+   egypt to resolve packaging and licensing issues 
 
 You can use the the "./tools/msftidy.rb" script to do some rudimentary
 checking for various violations.
@@ -23,17 +27,22 @@ checking for various violations.
 Code No-Nos
 ===========
 
-1. Don't print to standard output.  Doing so means that users of
+1. Don't print to standard output. Doing so means that users of
 interfaces other than msfconsole, such as msfrpc and msfgui, won't see
 your output.  You can use print_line to accomplish the same thing as
 puts. 
 
-2. Don't use "sleep". It has been known to cause issues with
+2. Don't read from from standard input, doing so will make your code 
+lock up the entire module when called from other interfaces. If you 
+need user input, you can either register an option or expose an 
+interactve session type specific for the type of exploit.
+
+3. Don't use "sleep". It has been known to cause issues with
 multi-threaded programs on various platforms. Instead, we use
 "select(nil, nil, nil, <time>)" throughout the framework. We have
 found this works around the underlying issue.
 
-3. Always use Rex sockets, not ruby sockets.  This includes
+4. Always use Rex sockets, not ruby sockets.  This includes
 third-party libraries such as Net::Http.  There are several very good
 reasons for this rule.  First, the framework doesn't get notified on
 the creation of ruby sockets and won't know how to clean them up in
@@ -45,19 +54,19 @@ already implemented with Rex and if the protocol you need is missing,
 porting another library to use them is straight-forward.  See our
 Net::SSH modifications in lib/net/ssh/ for an example.
 
-4. When opening an IO stream, always force binary with "b" mode (or
+5. When opening an IO stream, always force binary with "b" mode (or
 using IO#binmode). This not only helps keep Windows and non-Windows
 runtime environments consistent with each other, but also guarantees
 that files will be treated as ASCII-8BIT instead of UTF-8.
 
-5. Don't use String#[] for a single character.  This returns a Fixnum in
+6. Don't use String#[] for a single character.  This returns a Fixnum in
 ruby 1.8 and a String in 1.9, so it's safer to use the following idiom:
 	str[idx,1]
 which always returns a String.  If you need the ASCII byte, unpack it like
 so: 
-	str[idx,1].unpack("C")
+	str[idx,1].unpack("C")[0]
 
-6. Whenever possible, avoid using '+' or '+=' to concatenate strings.
+7. Whenever possible, avoid using '+' or '+=' to concatenate strings.
 The '<<' operator is significantly faster. The difference will become
 even more apparent when doing string manipulation in a loop. The
 following table approximates the underlying implementation:
@@ -74,10 +83,20 @@ following table approximates the underlying implementation:
 Note that the original value of 'b' is lost in the second case. Care
 must be taken to duplicate strings that you do not want to modify.
 
-7. For other Ruby 1.8.x/1.9.x compat issues, please see Sam Ruby's
+8. For other Ruby 1.8.x/1.9.x compat issues, please see Sam Ruby's
 excellent slide show at <http://slideshow.rubyforge.org/ruby19.html>
 for an overview of common and not-so-common Ruby version related gotchas.
 
+9. Never, ever use $global variables. This applies to modules, mixins,
+and libraries. If you need a "global" within a specific class, you can
+use @@class_variables, but most modules should use @instance variables
+to store information between methods. 
+
+10. Do not define CONSTANTS within individual modules. This can lead to
+warning messages when the module is reloaded. Try to keep constants
+inside libraries and mixins instead.
+
+
 Creating New Modules
 ====================
 
@@ -113,7 +132,8 @@ Licensing
 By submitting code contributions to the Metasploit Project it is
 assumed that you are offering your code under a BSD or similar
 license.  MIT and Ruby Licenses are also fine.  We specifically cannot
-include GPL code. 
+include GPL code. LGPL code is accepted on a case by case basis for
+libraries only and is never accepted for modules.
 
 When possible, such as aux and exploit modules, be sure to include
 your license designation in the file in the appropriate place.