home »
zui »
page

zui: General Conventions

NOTE: These conventions are currently being rewritten for updated HTML5/CSS3 and progressive enhancement.

ZUI methodology always uses the conventions of the chosen platform/environment/framework wherever possible/feasible/realistic. The most important issue is consistency per project. As long as the project is consistent the conventions don’t matter so much to me.

In general:

  • Indentation: soft tab (4) spaces

    • One True Brace style (1TBS)
    • Indent all matching open/close structures (see 1TBS)
    • Shorter lines of code, each unique declaration/expression on it’s own line
    • Do indent CSS i.e. related/nested selectors in logical groupings
  • Use whitespace i.e. after commas/colons, between declarations/expressions on a single line
  • Comment everything (in appropriate language pattern e.g. phpdoc
  • Never use “-” (dashes). Always use “_” (underscores). For easier text selection.
  • If no framework conventions for directory structure exist then… 
    root/
    /_assets/
        /css/
            style.css | common.css | default.css (choose)
            other.css
        /js/
            /libraries/
                jquery.js
                jquery.some_plugin.js
                some_other_library_plugin.js
            plugins.js
            script.js
    /_lib/
        /functions/
            some_function_library.php
        /LiteralClassName/
            ChildClassName.php
        /LiteralClassName.php
    /_vendor/
        /developer/
            /library_or_project/
                however the project ships | same structure as lib
Naming conventions
If no explicit convention is chosen, an environment doesn’t dictate,
or I’m left to my own devices I use the best of the above with the following conventions are used.

File naming
Format Use
_directory_name Directory containing files that should not be loaded directly and could/should be protected.
directory_name Normally viewable directory.
_file_name.ext Included file.
file_name.ext Normally viewable file.
FileName.ext Class file.
One class per file. Child classes stored in directory by the same name as parent class.
File formatting
Topic Use
Indenting Soft tab. (4) spaces.
Arguments $argument, $argument. Space after commas.
Variable, Class, CSS, html element naming
Format Use
css_class_name 

css_id_name

variable_name

 Lowercase. Underscore for space.
CONSTANTVARIABLE
CONSTANT_VARIABLE		 Uppercase. With or without underscores for spaces.
Directory Structures

Directory Structures

Coming. Need a way to include/share common stuff like this (shortcodes?) that was part of an included file from the pre-WordPress version of the site.

Coding standard references

Naming conventions and coding standards

php

  • pear coding standards
    With some minor exceptions/preferences for things like using the “one true bracket”, flexible adherence to 80-120 character lines (especially for certain comments) and other spacing in classes. The point being that most the pear standards increase readability and improve consistency which is the goal, especially when you are working in teams where consistency is vital.
  • ZEND Framework coding standards
    Mostly the naming conventions especially for classes.
  • Horde coding standards
    More good patterns
  • CodeIgniter Best Practices

ruby

rails