History of CodingGuidelines

Differences from version 16 to 26



@@ -1,38 +1,51 @@

-{toc}
+{maketoc}
 
-These CodingGuidelines are enforced for code that is a part of the standard bitweaver distribution. If you start your own package, you are welcome to choose whatever standards you like. However, if you play in core sandbox, we need to keep things need and tidy. We have a good bit legacy code that does not follow our own conventions, however, we are fixing as fast as we can with the ArchitectureTransition.
+These CodingGuidelines are enforced for code that is a part of the standard bitweaver distribution. If you start your own package, you are welcome to choose whatever standards you like. However, if you play in core sandbox, we need to keep things neat and tidy. We have a good bit of legacy code that does not follow our own conventions, however, we are fixing as fast as we can with the ArchitectureTransition.
 
-!!File Types and Naming Conventions
+!File Types and Naming Conventions
 
 There are several type of files, and each should be name as follow
-*__Presentation files__, such as "wiki/list_pages.php", should be named with an underscore seperateing each word. i.e. list_pages.php, and all lower case. There should be no reference to "tiki" in the file name, and it is best to keep the names short, and not redundant with the package they are in. For example "articles/edit_article.php" should be simple "articles/edit.php"
-*__Included files__ if your file is only included by other files and never invoked directly, it should follow the same rules athe presentation files, however, it should have _inc.php at the end, such as "wiki/page_setup_inc.php"
-*__Class files__ shoud be named identically to the name of the class they contain, i.e. "TikiSystem.php". There should be NO CODE outside of the class definition, and nothing should be declared. Sometimes, it is practical to put global function definitions in the class files, and that is acceptable. Classes should be declared in a presentation or include file.
-*__Library files__ are nothing but a big pile of preocedural function definitions and have "_lib.php" at the end, such as "util/zip_lib.php". There is a bunch of legacy TikiWiki stuff like the StatsLib class in stats/stats_lib.php - one day we will get around to cleaning this stuff up.
-*__Template files__ are for smarty, and they should follow convetion for presentation files, such as "wiki/templates/show_page.tpl"
+* __Directories__ should always be lowercase with underscores separating words - if possible, use only one word, that describes the directory best
+* __Presentation files__, such as "wiki/list_pages.php", should be named with an underscore separating each word. i.e. list_pages.php, and all lower case. There should be no reference to "tiki" in the file name, and it is best to keep the names short, and not redundant with the package they are in. For example "articles/edit_article.php" should be simple "articles/edit.php"
+* __Included files__ if your file is only included by other files and never invoked directly, it should follow the same rules as the presentation files, however, it should have _inc.php at the end, such as "wiki/page_setup_inc.php"
+* __Class files__ should be named identically to the name of the class they contain, i.e. "BitSystem.php". There should be NO CODE outside of the class definition, and nothing should be declared. Sometimes, it is practical to put global function definitions in the class files, and that is acceptable. Classes should be declared in a presentation or include file.
+* __Library files__ are nothing but a big pile of procedural function definitions and have "_lib.php" at the end, such as "util/zip_lib.php". There is a bunch of legacy ((TikiWiki)) stuff like the StatsLib class in stats/stats_lib.php - one day we will get around to cleaning this stuff up.
+* __Template files__ are for smarty, and they should follow convention for presentation files, such as "wiki/templates/show_page.tpl"
 There are a few special file names that the KernelPackage will look for in each Package. Below is an example for a fictional package named "somepackage":
-#__somepackage/tiki_setup_inc.php__ is automatically parsed by the KernelPackage at setup time (technically by TikiSystem::scanPackages()
-#__somepackage/templates/admin_somepackage.tpl__ and __somepackage/admin/admin_somepackage_inc.php__ are automatically assumed, and will be included if you link to www.yoursite.com/kernel/admin/index.php?page=somepackage
+# __somepackage/bit_setup_inc.php__ is automatically parsed by the KernelPackage at setup time (technically by BitSystem::scanPackages()
+# __somepackage/admin/upgrades/<version>.php__ is used to set package versions and control ((Package Upgrades)).
+# __somepackage/admin/schema_inc.php__ is used by kernel and install services to define tables for the package.
+# __somepackage/admin/admin_somepackage_inc.php__ and the corresponding __somepackage/templates/admin_somepackage.tpl__ are automatically assumed, and will be included if you link to www.yoursite.com/kernel/admin/index.php?page=somepackage
+# __somepackage/templates/menu_somepackage_admin.tpl__ allows specification of the package admin menu.
+# __somepackage/icons/pkg_somepackage.png__ icon for the package should be 48x48 pixels.
 
-!!Coding Conventions
-*Sometimes we need to hack something together with the intention of fixing it later. Such code should be commented with a comment starting with "@todo" and explaining what needs to be done and why it wasn't done right. Using "@todo" will make the text turn up in the source documentation if ((doxygen)) is configured to show it.
-* __variable names__ are all in the camelCaps OO/Java convention. There are several underscored variables floating around, and those how we tell the unmodified TikiWiki code.
-* __method function names__ functions in classes follow the OO/Java convention of camelCapFunction, note leading lowercase. There are several underscored methods floating around, and those how we tell the unmodified TikiWiki code.
-* __hash keys__ should be all lower case with an underscore between words like $post['last_modified'] - this makes life very easy and consistent between web forms and database inserts.
+!Coding Conventions
+* One of our most important rules in bitweaver, is to never commit code where you know it breaks something. If you __have to__ commit something you want to have tested by others, please add appropriate comments to the code such as:
++ // @TODO: Fix this function to work with foo. TODO is recognised by Doxygen and text editors like vim and will be highlighted in the source code.
+* __variable names__ are all in the camelCaps OO/Java convention. There are several underscored variables floating around, and those how we tell the unmodified ((TikiWiki)) code.
+* __method function names__ functions in classes follow the OO/Java convention of camelCapFunction, note leading lowercase. There are several underscored methods floating around, and those how we tell the unmodified ((TikiWiki)) code.
+* __hash keys__ should be all lower case with an underscore between words like ~np~$post['last_modified']~/np~ - this makes life very easy and consistent between web forms and database inserts.
 * __global function names__ global functions, and we only have a few, follow the stand php/C convention of underscored_function_name
 * To summarize naming of functions - each follows established coding conventions and each is different, however consistent.
 * __global variables__ must be in the format __$g__''VariableName'' like $gBitSystem
 * __function parameters__ should be prefixed with __$p__, like: function foo( $pBar )
-* all __define(CONSTANT)__ that you consider configurable by the user should have an __if( defined(CONSTANT) )__ check beforehand.
-* Please follow traditional unix brace policy. Paren styles vary, and are up to individual preference:
- function foo( $pBar ) {
- if( condition ) {
- ...
- }
- }
+* all __define( CONSTANT )__ that you consider configurable by the user should have an __if( defined( CONSTANT ) )__ check beforehand.
+* Please __don't use ridiculous abbreviations__. the code should be easy to follow by people other than yourself
+* Please follow traditional unix brace policy. Parentheses styles vary, and are up to individual preference:
+{code source=PHP}
+function foo( $pBar ) {
+ if( condition ) {
+ ...
+ }
+}
+{/code}
+* __For adding Javascript__ we have some specific ((Javascript Coding Guidelines)), which build on these coding conventions.
 
-!!Config Files
+!Config Files
 * __ kernel/config_inc.php __ is for the users custom settings that override settings declared later on in the process. This should only be included directly by config_defaults_inc.php and during the install.
 * __ kernel/config_defaults_inc.php __ checks and includes config_inc.php if it exists. All defaults should be defined in this file, not in the code. config_default_inc.php should only be called from setup_inc.php. Only setting of variables and logic in setting of variables should be in this file.
-* __ kernel/setup_inc.php __ defines constants and sets up the environment for bitweaver. It includes the file config_defaults_inc.php which inturn includes config_inc.php. Once these files are included, logic and insanity checks are performed along with setting up of constants, etc. If a user wishes to over-ride anything by including it in config_inc.php, the code here must not complain (ie if(!defined(SOME_CONST)) { define('SOME_CONST'...etc) unless a sanity check has failed.
+* __ kernel/setup_inc.php __ defines constants and sets up the environment for bitweaver. It includes the file config_defaults_inc.php which in turn includes config_inc.php. Once these files are included, logic and insanity checks are performed along with setting up of constants, etc. If a user wishes to over-ride anything by including it in config_inc.php, the code here must not complain (ie if(!defined(SOME_CONST)) { define('SOME_CONST'...etc) unless a sanity check has failed.
+
+! Sub Pages
+{toc}
 
Page History
Date/CommentUserIPVersion
17 Mar 2009 (21:16 UTC)
package icon
Daniel Sutcliffe71.161.102.626
Current • Source
Daniel Sutcliffe71.161.102.624
View • Compare • Difference • Source
Daniel Sutcliffe71.161.102.623
View • Compare • Difference • Source
laetzer85.178.62.11722
View • Compare • Difference • Source
xing194.152.164.4520
View • Compare • Difference • Source
xing194.152.164.4519
View • Compare • Difference • Source
Jerry Russell66.25.205.23218
View • Compare • Difference • Source
xing194.152.164.4517
View • Compare • Difference • Source
spiderr66.93.240.20416
View • Compare • Difference • Source
spiderr66.93.240.20415
View • Compare • Difference • Source
spiderr66.93.240.20413
View • Compare • Difference • Source
Jan Lindåker192.16.134.6612
View • Compare • Difference • Source
spiderr66.93.240.20411
View • Compare • Difference • Source
Stephan Borg218.214.1.11310
View • Compare • Difference • Source
Stephan Borg218.214.1.1139
View • Compare • Difference • Source
SEWilco209.98.144.168
View • Compare • Difference • Source