Programming Notes

IMPORTANT ZUHA PROGRAMMING NOTES

This is a list of items to check when reviewing code added to Zuha (and/or check before committing code to Zuha).

Programmer Prerequisites :

Know git, and a wamp (like) stack installed

Code formatting rules :

1. Variables = lowerUpperCase : We should be using well named and formatted variables whenever possible. (ex. $catalogItems, NOT $dat or $catalog_items)
2. Use proper spacing and line breaks : (the code should be easily readable)
3. Clean SQL files : Use utf8 and auto increment = 1 (not latin, etc) when added sql to the versions folder.
4. Use single quotes and double quotes in a standardized way : html = double quotes, php = single quotes, javascript = double quotes
5. Public Method Naming = under_score() : actions which are accessible by url
6. Method Naming = sameAsVariableCase() : model and controller function which aren't accessible by url.
7. model names = CamelCase (singular)
8. controller names = CamelCases (plural)

Database Update rules :

1. DB table formatting and conventions : Plugins should always use a version of plugin name as the table prefix. (ex. projects, project_issues, projects_users), and if you create a new table or field, try to leave notes about what its for in the table itself using the comments field.
2. Required DB table fields : All tables require "id (PRIMAR NOT NULL VARCHAR 36)", "creator_id (NULL VARCHAR 36)", "modifier_id (NULL VARCHAR 36)", "created (NULL DATETIME)", "modified (NULL DATETIME)".
3. All "_id" fields should be VARCHAR (36).

PHP Programming use rules :

1. Use Heavy Models : Controllers are for requesting data from the model, and then defining variables so that they are prepared for the Views. Controllers should not be manipulating variables before sending them to the model. The model should do it, so that it can be reused when other controller actions want to perform a similar function.
2. Use throw / catch / exceptions syntax.
3. Use saveAll() : If you need to filter info from saveAll, then you need function within the same model called cleanData(), which takes care of missing data, and/or reformatting before sending to saveAll() or updateAll().
4. Use Proper Form Input Names : In order to use saveAll() we have to make sure that we use $data[Model][0][field] when there are hasMany and HABTM relationships. (no fudging and extra code to reformat when not necessary)
5. UsableBehavior : ACL works for most cases, BUT, if you want particular records to be editable by particular users related in a HABTM way, then you need your own ACL for that object or to use the UsableBehavior. (ie. if you want individual friends only to see your profile, then we would need custom access control for that plugin.)
6. Model data arrays : Always use a $this->data-like formatted array for public model functions. (This is what allows us to use workflows and the custom form builder) Ex. Custom Notification Model Function. for example.

sendText($data = array) { echo $data[‘Model’][‘field’]; }

1. Use the enumerations table (do not use enum field type): For “types / labels / quasi-categorization” which may be changed later. This is what will allow easy name changes in multi-sites. Combine enumerations table values with hard coded required values to make customizable and required enumerations work together. Ex. Make a model function which outputs all types in an array formatted for select drop downs. ( ex. Gallery->types() { return array_merge(array(‘gallery1’ => ‘Gallery Type One’), enum('Gallery Type')); } ) (The main point is that an enum field type should not exist in the data base).

Javascript Programming use rules :

1. Make sure js loads when the page loads : Often you make it so that a form works when clicked or changed, and forget that the page can be reloaded with the form input already selected. Typically these functions should also work on page load, not just when the inputs change.