Naming Conventions

Abstractions Used in API (Class Interfaces)

When creating or extending the internal Bluewater MVC API, methods/functions must identify abstractions using a compound name, separate the names using underscores, not camelCase.

For example, the name used for the MySQL PDO driver is “pdo_mysql”, not “pdoMysql”. When the developer needs to use a string, normalize it to lowercase. Where reasonable, add constants (all uppercase) to support this (e.g. PDO_MYSQL).

Classes

A Framework should employ a class naming convention whereby the names of the classes directly map to the directories in which they are stored. The root level directory of a Framework is named by the name of the Framework, for instance the “library/Bluewater/” directory, under which all classes are stored hierarchically.

Class names may only contain alphanumeric characters. Numbers are permitted in class names but are discouraged. Underscores are only permitted in place of the path separator. For example, the class “Bluewater_DB_Table” will map to the path “library/Bluewater/DB/Table.php”.

If a class name is comprised of more than one word, the first letter of each new word must be capitalized. Successive capitalized letters are not allowed; e.g., a class “Bluewater_PDF” is not allowed, while “Bluewater_Pdf” is to be used. Why? The autoloader that handles the access and retrieval of class files assumes that the directory and files names will follow this structure as well. This is not an issue on a Windows server, but Linux will bark, since it is a case-sensitive OS.

Classes that belong to Bluewater must always start with Bluewater. E.g. “Bluewater_” and must be stored under the “library/Bluewater/” directory hierarchy accordingly. These are examples of acceptable names for classes:

Bluewater_DB

Bluewater_DB_Table

Bluewater_Controller

IMPORTANT: Code that operates with the framework but is not part of the framework, such as code written by a framework end-user must never start with the framework’s name; e.g. “Bluewater_”, but reside within its own hierarchically structure.

Interfaces

Interface classes must follow the same conventions as other classes (see above), but must end with “_Interface”, such as in these examples:

Bluewater_Log_Adapter_Interface

Bluewater_Controller_Dispatcher_Interface

Filenames

For all other files, only alphanumeric characters, underscores, and the dash character (”-”) are permitted. Spaces are prohibited. Any file that contains any PHP code must end with the extension ”.php”. These examples show the acceptable filenames for containing the class names from the examples in the section above:

/library/Bluewater/Db.php

/library/Bluewater/Db/Table.php

/library/Bluewater/Controller.php

/library/Bluewater/Controller/Dispatcher/Interface.php

Functions and Methods

Function names may only contain alphanumeric characters. Underscores are not permitted (Don’t confuse this with private methods). Numbers are permitted in function names but are discouraged. Function names must always start with a lowercase letter. When a function name consists of more than one word, the first letter of each new word must be capitalized. This is commonly called the “studlyCaps” or “camelCaps” method. Verbosity is encouraged. Function names should be as illustrative as is practical to enhance understanding. These are examples of acceptable names for functions:

filterInput()

getElementById()

addAttachement()

For object-oriented programming, accessors methods for object members should always be prefixed with either “get” or “set”. When using design patterns, such as the Singleton or Factory patterns, the name of the method should contain the pattern name, where practical, to make the pattern more readily recognizable. Though function names may not contain the underscore character, class methods that are declared as protected or private must begin with a single underscore, as in the following example:

class Bluewater_Foo
{
   protected function _fooBar()
   {
      // ...
   }
}

Functions in the global scope (“floating functions”) have to be wrapped in an abstract class and declared static.

Variables

Variable names may only contain alphanumeric characters. Underscores are not permitted [except in Class methods]). Numbers are permitted in variable names but are highly discouraged. For class member properties that are declared with the private or protected construct, the first character of the variable name must be a single underscore. This is the only acceptable usage of an underscore in a variable name. Member variables declared as “public” may never start with an underscore. For example:

class Yacs_Foo
{
   public $foo;
   protected $_bar;
   private $_zed;
}

Like function names, variable names must always start with a lowercase letter and follow the “camelCaps” capitalization convention. Verbosity is encouraged. Variable names should always be as verbose as practical. Terse variable names such as “$i” and “$n” are discouraged for anything other than the smallest loop contexts. If a loop contains more than 20 lines of code, variables for such indices or counters need to have more descriptive names. For instance: “[cci]$fooBarCounter[/cci]”.

Constants

Constants may contain both alphanumeric characters and the underscore (except as the first character). Numbers are permitted in constant names but are discouraged. Constant names must always have all letters capitalized. To enhance readability, words in constant names must be separated by underscore characters. For example, “SUPPRESS_EXCEPTION” is permitted but “SUPPRESSEXCEPTION” is not. Constants should be defined as class members by using the “const” construct, where possible. Defining constants in the global scope with “define” is only permitted in exceptional cases.

// need code example here

  1. #1 by Anonymous on February 4, 2010 - 1:06 am

    Glad to see that this site works well on my iPhone , everything I want to do is functional. Thanks for keeping it up to date with the latest.

  2. #2 by col brakey on February 18, 2010 - 7:14 pm

    Hi. I wanted to make you aware that some components of your web site are onerous to scan for me, as I am color blind. I suffer from deuteranopia, however there are other sorts of color blindness which will also have problems. I can read the majority of the web page OK, and the elements I have difficulties with I am able to comprehend by using a special browser. Just the same, it’d be great if you would bear in mind us color-blind surfers while undertaking the next web page design. Thanks.

  3. #3 by Nathanael World on February 28, 2010 - 3:06 pm

    Though I would’ve loved it much more if you added a relevant video or at least pictures to back up the explanation, I still thought that your write-up quite helpful. It’s usually hard to make a complicated matter seem very easy. I enjoy your weblog and will sign up to your feed so I will not miss anything. Fantastic content

  4. #4 by Cia on March 10, 2010 - 6:42 am

    Excellent article, I will take note. Many thanks for the story!

  5. #5 by Versed on March 13, 2010 - 10:23 am

    I really like when people are expressing their opinion and thought. So I like the way you are writing

  6. #6 by Wilmington on March 14, 2010 - 4:32 am

    Thanks for an idea, you sparked at idea from a perspective I hadn’t considered yet. Now lets see if I can do something with it.

  7. #7 by Reid Chambley on March 19, 2010 - 12:55 am

    Interesting blog you got here but I can’t seem to find the RSS button.

  8. #8 by Tonia Allday on April 14, 2010 - 1:06 am

    Hello. Good job. I did not expect this on a Wednesday. This truly an excellent story. Thanks!

  9. #9 by reverse phone lookup on April 14, 2010 - 12:45 pm

    I always like reading such intelligent articles by a person who is so obviously knowledgable on their chosen subject. I’ll be following this thread with much interest. Keep up the good work and I look forward to seeing this site go from strength to strength!

  10. #10 by Anonymous on May 17, 2010 - 10:18 am

    You certainly deserve a round of applause for your post and more specifically, your blog in general. Very high quality material

  11. #11 by Stanton Ragan on May 29, 2010 - 1:06 pm

    As a Newbie, I am always searching online for articles that can help me. Thank you

  12. #12 by Jake Call on May 30, 2010 - 8:02 am

    Creative writing, really nice. thanks for posting.

  13. #13 by Mitchell Devino on June 10, 2010 - 2:02 am

    Very informative post.Thanks Again. Awesome.

  14. #14 by Delorse Zinner on September 16, 2010 - 6:13 pm

    Thank you for another informative blog. Where else could I get that kind of info written in such a perfect way? I have a project that I am just now working on, and I have been on the look out for such information.

  15. #15 by Norbert Besares on September 19, 2010 - 11:07 am

    Brilliant blog posting. I found your post very interesting, I think you are a brilliant writer. I added your blog to my bookmarks and will return in the future.

  16. #16 by Vonderkell on September 20, 2010 - 9:18 pm

    I checked out something comparable to your “Naming Conventions | Bluewater MVC” post at techcrunch… anyway, I feel that I mostly aggree with what you discuss here…

  17. #17 by Cody Morkve on September 24, 2010 - 10:51 am

    I hope you will keep updating your content constantly as you have one dedicated reader here.

Comments are closed.