[lucy-commits] [Lucy Wiki] Update of "LucyStyleGuide" by MarvinHumphrey

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Lucy Wiki" for change notification.

The "LucyStyleGuide" page has been changed by MarvinHumphrey.
The comment on this change is: Modernize for 2011.  Mention automatic code formatters.  Replace partial description of Clownfish naming coventions with reference to the Clownfish documentation.  .
http://wiki.apache.org/lucy/LucyStyleGuide?action=diff&rev1=2&rev2=3

--------------------------------------------------

  Consistency of style is especially important in Lucy because multiple programming languages are involved.  Virtually no contributors are likely to be equally fluent in all of them, and it is easier for those who are less fluent in a given language to comprehend code that adheres to a single style.
  
- Contributions should conform to the following set of guidelines.  Individual guidelines may be broken if necessary to achieve a clearer layout.
+ Contributions should conform to the following set of guidelines.  Individual guidelines may be broken if necessary to achieve a clearer layout, though the auto-formatters impose certain constraints.
  
  == All Languages ==
  
- Pronounceable identifiers are preferred over nms_wth_vwls_rmvd (names with vowels removed), as they are easier for non-native English speakers to parse.
+   * Pronounceable identifiers are preferred over nms_wth_vwls_rmvd (names with vowels removed), as they are easier for non-native English speakers to parse.
+ 
+   * An application named "lucytidy.pl" within {{{trunk/devel/bin/}}} which wraps various code beautifiers (AStyle, Perltidy, etc.) is used to format the Lucy source tree automatically.
  
  == C ==
  
- All C code should follow the guidelines spelled out in the Apache HTTPD C Style Guide: http://httpd.apache.org/dev/styleguide.html.
+   * Variables -- lower case with underscores.
  
- In addition, contributions should use these naming conventions:
+     {{{BitVector *bit_vec = NULL;}}}
  
-   * Module file names
+   * Global functions and methods -- Globally visible function names are constrained by Clownfish's naming conventions.  See the documentation for Clownfish.
  
-    Upper``Camel``Case.
+   * Static functions -- Ordinary static functions should be prepended by "S_": 
  
-    {{{./src/c/Lucy/Util/BitVector.h}}}
+     `static int64_t`<<BR>>
+     `S_refill(InStream *self);`
  
-   * Struct definitions
+   * Static inline functions -- Exported static inline functions within .cfh/.h header files should follow Clownfish naming conventions.  Static inline functions within .c files should be prepended by "SI_":
  
+     `static INLINE int64_t`<<BR>>
+     `SI_tell(InStream *self);`
-    Upper``Camel``Case.  Globally visible struct definitions are
-    prefixed by 'lucy_'.
- 
-    {{{lucy_BitVector}}}
- 
-   * Variables
- 
-    Lower case with underscores.  Globally visible variables are
-    prefixed by 'lucy_'.
- 
-    {{{bit_vec}}}
- 
-   * Functions
- 
-    Lower case with underscores.  Globally visible functions are
-    prefixed by 'lucy_Nick``Name_', where Nick``Name is a shortened
-    version of the name of the module where the function is
-    located.  Special global functions defined in Globals.h omit
-    'Nick``Name_' (though they are still prefixed by 'lucy_').
- 
-    {{{lucy_BitVec_destroy}}}
- 
-   * Macros
- 
-    Mixed case, starting with a capital letter, multiple words
-    separated by underscores. Prefixed with 'Lucy_Nick``Name_' if
-    globally visible.
- 
-    {{{Lucy_BitVec_Next_Set_Bit}}}
- 
-   * Constants
- 
-    All upper case with underscores.  Prefixed with LUCY_NICKNAME_ if
-    globally visible.
- 
-    {{{LUCY_BITVEC_SENTINEL}}}
  
  == Perl ==
  
  All code should follow perlstyle.
  
- Formatting is handled automatically using the app {{{$DIST_ROOT/devel/lucytidy}}}, which is perltidy with a preference set derived from guidelines laid out in Damian Conway's book 'Perl Best Practices'.
+ Formatting is handled automatically using Perltidy with a perltidyrc file derived from the guidelines laid out in Damian Conway's book 'Perl Best Practices'.
  
  == Ruby ==