Sourceforge.net - The VCF's Project Host
   The VCF Website Home   |   Online Discussion Forums   |   Sourceforge.net Project Page   

1.7. Standards

Please read the naming standards documentation before you start changing all sorts of things. These standards must be followed for any code that gets entered into the main VCF development tree.

To get familiar with things build the VCF if you haven't already done so, and then check out some of the example code in the vcf/examples directory.

If you're unsure where to go next, try taking a look at the bug list or tasks list at the project page. Also feel free to contact anyone on the project or stop by the project forums for more information.

1.7.1. Coding and Naming Standards

The following are setup here to attempt to increase the readability of the VCF source code. Developers interested working on the framework proper, must adhere to these guidelines. Any questions regarding this, please email me.

[Note]Note
Much of this is rehashed from naming standards used on other projects, so there is nothing new here, and tries to use as much common sense as possible. Folks who are familiar with Borland's Delphi, Sun's Java, or (gasp...) Microsoft's .NET naming conventions will probably recognize a great deal here.

Do not use Hungarian notation at all in any code that is in the main VCF development tree. Code submitted like this will be removed or ignored (if submitted as a patch).

Capitalization Styles. 

There are two main capitalization schemes the VCF uses:

Camel casing: 

Capitalizes the first character of each word except the first word. For example:

fileStream
			

Pascal casing: 

Capitalizes the first character of each word. For example:

FileStream
			

The following table indicates which styles are used for the various types/identifiers.

Table 1.2. 

TypeCaseComments
ClassPascal casing 
enumerated valuesCamel casing 
enumerated typePascal 
Member function, regular functionsCamel casing 
NamespacesPascal casing 
RTTI property nameCamel casing 
Function argumentsCamel casing 
Member variablesCamel casinguses "_" suffix
regular variablesCamel casing 

Class naming. 

Classes should be named with nouns or noun phrases, with more or less abstraction in the name depending on it's usage. For example, a common base class for describing objects that represent bananas, apples and oranges might be Fruit, with a class called Banana deriving from Fruit.

  • Pascal casing

  • No prefixes, like "C", or "vcf" or whatever. If you really need a prefix then you probably need the class inside of a namespace.

  • Keep away from abbreviations if at all possible. Common ones like IO, or UI are OK, but please use sparingly.

  • No underscores.

Examples:

FileStream

ClassRegistry

Control					
			

Enumerated values. 

Enumerated values should have a descriptive name of what the value represents. The value names should use a prefix that is an acronym of the upper case characters of the enumeration type.

  • Camel casing

  • Prefixes are OK, but must follow the rules above, see example

  • Keep away from abbreviations if at all possible. Common ones like IO, or UI are OK, but please use sparingly

  • No underscores

Examples:

enum FruitBaskets {
fbLittleBasket = 0,
fbMediumBasket,
fbElGrandeBasket  
};

enum MessageStyle {
msDefault = 0,
msError,
msInfo,
msWarning
};
			

Enumerated types. 

Names should be clearly descriptive of the type and what it represents. When appropriate please nest the enum type inside of the class it is associated with (don't forget to place it at public scope so others may use, assuming that is the intent).

  • Pascal casing

  • No prefixes

  • Keep away from abbreviations if at all possible

  • No underscores

Example

Dialog::MessageStyle

AlignmentType
			

Always refer to enum types that are part of a class with the class name.

Example

Dialog::MessageStyle, 

//as opposed to
MessageStyle
			

Class member function naming. 

Use names that have verbs or verb phrases that clearly express what the function will do. Functions that return a true or false value should try and use the "is" or "has" in front of the name, i.e. isEmpty() or hasData().

  • Camel casing

  • Keep away from abbreviations if at all possible

  • No underscores, unless the function's scope is forced to be public but is not meant for general usage(for whatever reason). In this case a "internal_" should be prefixed to the name of the function.

Example:

class Foo : public VCF::Object {
public:

String getName();

void internal_doSomething( int someValue );
};
			

Class member variable naming. 

Use adjectives that clearly describe what the member is and how it should be used. All member names must use the "_" suffix convention.

  • camel casing

  • Keep away from abbreviations if at all possible

  • a single underscore suffix only, no underscores in the actual name

  • no Hungarian notation

Example:

class Foo {
public:
protected:
int countOfBarObjects_;
String name_;
};
			

Variable naming. 

Use descriptive names that clearly identify what the variable should do or what it means rather than identifying it's type. Do not use Hungarian notation.

  • Camel casing

  • Keep away from abbreviations if at all possible

  • No underscores

  • No Hungarian notation

Example:

			

Function naming. 

Use names that have verbs or verb phrases that clearly express what the function will do.

  • Camel casing

  • Keep away from abbreviations if at all possible.

  • No underscores

Example:

			

Use of Namespaces. 

Use namespaces to group a large collection of classes, typedefs, etc together, to more clearly identify the classes. Use namespaces in place of class prefixes or function prefixes. For example instead of the classes PDQFileDialog, PDQDumper, and PDQBigStuff, create a namespace called PDQ and rename the classes to FileDialog, Dumper, and BigStuff, and place them inside of the PDQ namespace.

  • Pascal casing

  • Abbreviations are OK for namespaces

  • No underscores

Example:

			

Use of static class methods/members. 

see Function naming and Member function naming above with the following restrictions:

  • No underscores at all

All static members must always be referenced with the class name that they are part of, never just by themselves, or by a class instance.

Example:

//declaration:
class Foo {
public:
static String commonBarRepository;
};

//initialization:
String Foo::commonBarRepository = "some useful initial value";

//usage:

//OK
String s = Foo::commonBarRepository;

//Unacceptable, even with the scope of class Foo
String s = commonBarRepository;

//Also unacceptable
Foo f;
String s = f.commonBarRepository;					
			

Comments. 

The standard comment style used in the VCF is comparable to what is used in Java, i.e. the

/**
*/
			

style.

Headers with the following should be documented

  • Namespaces

  • Structs

  • Unions

  • Classes

  • Class/Struct/Union members (semi optional depending on what it is and how clear the name is)

  • Class methods

  • Enums

  • Functions

  • custom #defines

The rationale for this is to allow for automatic source level documentation by processing all headers through doxygen. Document the headers. Document your classes. More documentation is better that no documentation. Be as clear and concise as possible in explaining what something does. You can and should use html markup tags for further clarity, for example the <B> tag to emphasize some point or word, or use the "\em" doxy tag for this. Also where applicable, feel free to put a sample piece of code that illustrates proper usage. Use the <PRE> tags for this. Note that you can also use the doxygen "\code" and "\endcode" tags as well.

The preferred format for documenting a class is to use the doxygen command "\class" to specify the class name and it's proper include file, followed by the first paragraph with no "\par" command. Successive paragraphs need to use the "\par" command. Doing so ensures that the doxygen properly picks up you first sentence for use in it's "brief" comments section for your class. For example:

/**
\class FooBar FooBar.h "vcf/FoundationKit/FooBar.h"
Initial paragraph explaining what this class does.
\par
Further paragraphs explaining what this does...
*/
class FooBar {
//rest of code omitted...
};
			

The last part of the "\class" command specifies the directory path of the include file. If you are adding a new class to on the VCF kits, then the proper format is "vcf/" plus the kit name, followed by the actual header file name. So if you added a new CalendarControl to the ApplicationKit, the path would be "vcf/ApplicationKit/CalendarControl.h".

Do not pollute the code, particularly the headers, with tons of "//" spacers a-la what Microsoft's Visual C++ generated code for classes does. Keep it clean.

For single line comments line comments you can use the "//" but it is still prefered that you use the

/**
comment
*/
			

style.

Use the @param, @return, @author, and @version to further clarify what paramaters/arguments and return values do, as well as the author and version of the item in question.The @version should be the current cvs version that you are working under. If you are not entirely sure what these do, look them up in JavaDoc (which is where they are from).

Example:

/**
This is what the method does...
@param void* this parameter is for....
@param bool this parameter indicates....
@param String the name of.....
@return int the return value is...
@author Jim Bob Snake
@version 0.5.9
*/
int myCoolMethod( void* d, bool b, String s );					
			

In addition to the javadoc style tags, since we use doxygen, you can also use the doxygen special tags for further control of formatting. Not all of the header docs use these yet, but for examples that do, see the following files:

  • vcf/src/vcf/FoundationKit/Locales.h

  • vcf/src/vcf/GraphicsKit/Image.h

  • vcf/src/vcf/GraphicsKit/PrintSession.h

Code Blocks. 

While I am sure this is mildly controversial, bordering on hysterical, or perhaps even blasphemous, I am going to set down some rules for code blocks, i.e. the famed "{" and "}". For consistencies sake please use the following guidelines for code that is in the VCF core source tree (i.e. anything under the vcf/src/vcf directory). Example code is free to diverge from this (though I would encourage it usage there too).

For function blocks do not write them on a single line, even for something as simple as a get method that just returns a member variable. The problem is that, at least on Microsoft compilers/debuggers (and almost certainly GCC/GDB as well), it becomes really difficult to step through code, or examine the variable(s). Beleive it or not, not all of us are assembly level debuggers!.

//Unacceptable			
class Foo {
public:
	int val_;
	
	int foo() { return val_; }
};

//OK
class Foo {
public:
	int val_;
	
	int foo() { 
		return val_; 
	}
};
			

For "if..then" blocks use the following:

if ( condition ) {
	//code
}
			

Please don't use

if ( condition ) 
	//single line of code

			

Use the "{}" brackets even with the one line. Please avoid using the following constructs:

//BAD!
if ( condition ) {
	//code
} else {

}

//OK
if ( condition ) {
	//code
} 
else {

}			

1.7.2. Documentation Standards and Generation

Introduction.  The VCF uses DocBook for all documentation that is not generated from source code. For source code generated documentation, we use doxygen. This section will concentrate on explaining how to edit and work with the VCF DocBook documentation. If you have never used DocBook before, take a glance at this CodeProject article that thoroughly explains how to get set up and running with DocBook on Win32 systems.

Generating the VCF DocBook files.  To generate the VCF documentation on a Win32 system, you have to have a few things set up:

Currently certain files used to build the VCF DocBook documentation require hard coded absolute paths to make sure that things work right. To generate the documentation on your own system, you'll need to edit a few files to make sure the paths are pointing to the right directories.

To start with edit vcf/docs/Makefile in your favourite editor. Make sure the HTMLHELP_COMPILER variable points to the correct directory on your machine. Keep the directories in quotes or make will barf. Make sure XSL_DOCBOOK_DIR points to where you have your DocBook xsl stylesheets installed.

Next edit vcf/docs/vcf.xsl. Make sure the line:

			
<xsl:import href="d:/code/docbook-xsl-1.68.1/htmlhelp/htmlhelp.xsl"/>
			
			

Points to the right doc book directory on your system where your DocBook XSL Stylesheets are found.

Once you've completed this, open a command line (if you are doing this on a Win32 system you'll need cygwin for this) and cd to vcf/docs. Type:

make coredocs_hh
			

This should generate the VCF documentation for you in HTML Help chm format (including all tutorials). Look for a file called "VCFDocs.0.6.8.chm" (or whatever the current version is set at).

Editing the VCF DocBook Documentation.  To edit the docs open and edit the various .xml files in the vcf/docs directory in your favorite text or xml editor. The main ones are :

  • corelib_applicationKit.xml - application Kit stuff

  • corelib_componentAuthoring.xml - component authoring

  • corelib_foundationKit.xml - FoundationKit docs

  • corelib_graphicsKit.xml - graphics kit docs

  • getting_started.xml - using the vcf and getting around the framework

  • general.xml - general vcf docs

Generating Tutorials.  To generate tutorials, open a command line, cd to vcf/docs and type

make tutorials
			

This will generate separate "articles" in each tutorial directory (with the top level directory being vcf/examples).

Editing and Adding Tutorials.  To add a tutorial article you have to edit/create several files to ensure that the tutorial documentation is added to the full VCF DocBook documentation, and that seperate articles can be created.

To start, edit vcf/docs/vcf_docbook.xml. At the top there are a number of ENTITY declarations, each of which point to specific file that contains further documentation. This is done to break the documentation into smaller, more manageable sections. To add a tutorial, you'll need to add a new entity for each tutorial. Let's say we had a tutorial for "FooBar", we'd add an entity for your tutorial(after the last ENTITY), like so:


<!ENTITY foobar SYSTEM "../examples/FooBar/FooBar.xml">

			

Now edit the vcf/docs/tutorials.xml file. This is organized first by kit (or library) and then by section for each tutorial. Find a section or create a new one and insert your entity that you created earlier. For our FooBar example we'll create a new one under the FoundationKit. Our example would look like this:


<section><title>FooBar</title>
	&foobar;
</section>
		
			

Note that the entity name is the same as you declared it in the vcf/docs/vcf_docbook.xml file.

Now you need to create the actual content itself. You must follow this format or things will break. cd to your examples directory

cd vcf/examples/FooBar
			

Create two files named like so:

  • <tutorial name-case sensitive>.xml

  • <tutorial name-case sensitive>Article.xml

For our example we'd create FooBar.xml and FooBarArticle.xml. Edit the FooBarArticle.xml file and add the following (this must go right at the begining of the file):


<?xml version="1.0" standalone="no"?>
<!DOCTYPE  book  PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [	
	<!ENTITY foobar SYSTEM "FooBar.xml">	
]>


<article>	
  &foobar;	
</article>


			

This will allow your content in FooBar.xml to either be used in the larger VCF DocBook documentation or allow it to be generated as a standalone article, suitable for posting on websites such as CodeProject.com.

Now add your actual documentation (following DocBook rules) to Foobar.xml.

Finally, to be able to actually generate the tutorials in a standalone manner, we need to make one more change to the vcf/docs/Makefile. Edit vcf/docs/Makefile and add your tutorial to the TUTORIAL_ARTICLES variable. For our example, we'd add:


TUTORIAL_ARTICLES = ../examples/HelloWorld/HelloWorldArticle.xml\
../examples/FooBar/FooBarArticle.xml

			

Save the makefile and your're done! cd to vcf/docs and type

			
make tutorials
			

You should end up with a FooBarArticle.html in your tutorials directory.

   Comments or Suggestions?    License Information