1. NAMING CONVENTION AND
COMMENTINGSTYLE FOR
CHRYSLERGFXCOMMUNICATION
APPLICATION
NAMING CONVENTION &COMMENT STYLE
JABED HOSSAIN, JUNIORBUSSINESSSYSTEMANALYST
GROUND EFFECTS LTD.
2775 St. Etienne Blvd
Windsor,Ontario.
NOVEMBER 29, 2016

2. 1 | P a g e
Table of Contents
Background and Overview _____________________________________2
Commenting ________________________________________________2
Class Comments ______________________________________3
Inline Comments _____________________________________3
Function Comments __________________________________4
Standardized Comment Hinting ________________________________4
Variable Names, Capitalizations and Convention __________________4
FileNames _________________________________________________5
Bibliography _______________________________________________5

3. 2 | P a g e
Background and Overview
Thisdocumentgrewoutof increasedfrustrationwhile conductingreverseengineeringonaprojectwhich
was examinedtofindsystemglitch. Asthe choicesof wordsare different fromdeveloperstodevelopers
to express singular or specific meaning, it is really crucial for developers to choose a particular naming
convention and coding style while developing applications. This document is built on the naming and
coding standard, the author followed while reverse engineering an outmoded application and re-
developing it with a new standard.
The document is broken down by subject matter to facilitate scanning [1]. The motivation of this
documentisto create a framework thatis usable forC# and C++ developmentatGround Effects Ltd and
may be extended to include other forms of development. The most important part of any code or style
documentshouldbe consistency,notthe minutiaof how toplacebrackets,semi-colonsormethodnames
[1]. This document is not going to discuss strength of particular development environment.
Commenting:
A nightmare for any developer, if the developer finds out a scratchy coding practice from their
predecessor on any project,the new developer is supposed to work with. C# has its own syntax specific
partsto define acommentblocksuchas /*-- --*/inC#andC++. Code commentscanbe brokendowninto
three primary types each with specific roles in the application [1]. They are as followings:
 Class Comments
 Inline Comments
 Function Comments
The ClassComments provideacontexttounderstandthefilethatthe developerisgoingtoworkon. Inline
comments provide context about the code right where the developer needs it. Lastly, Function
Commenting,providesnotonlybackgroundonaparticularmethod,butalsocreatesanice frameworkof
documentation for future reuse of the code [1].
Class Comments:
Thisis perhapsthe quickesttoimplementsince itcanbe addedto a defaultdocumenttemplateeasilyin
most authoring environments and provides much of the detail a later developer will need when this
document is opened years later, which exactly the author has faced [1]. Below the structure for Class
Commenting is described thoroughly:
/****
Title: This class builds database connection string
Project: ChryslerGFXCommunication
Author: Jabed Hossain
Description: This page uses .settings file to save database information. Mainly
settings file is used to create and access values that are persisted between application
execution session.
Created: November 28, 2016
Revision History:
November 29, 2016: Jabed Hossain -> Created f_setDBConnection ()
function to work with dbtype.
****/

4. 3 | P a g e
Some additionalinformationyoucanuse inside the titleblockcommentmayincludelicensinginformation
also copyrightnoticesthat are necessaryto put. While developingasystemwe mightneedto use some
librarieswhichisdevelopedbysome thirdparty.Givinganabstract descriptionof those librariescanalso
be a good choice. There cannotbe reallyachoice of how the commentingblockwillbe structured.Inthis
scenario, the author implemented class commenting like above.
Warning: If the Class/Page Comments are in a true HTML, XML or JavaScript document, it is exposed to
anyone whocaresto lookatthe source for itand thiscouldcompromise yoursitessecurity.Soitisawise
decision to add comments within the application language instead of text that is served to users. [1]
Inline Comments:
Asnamingvariablesdiffersbetweendevelopers,codingstylebetweendevelopersmightdifferfromeach
other as well. From initialization of variables, using constructors to choosing between implementing
interfaces or implementing base/child class concepts, developers might choose to implement different
coding styles to accomplish the same goal. These are the reason, inline commenting is one of the most
importantaspectsof cleancoding.There isparticularreasonfora programmertothinkthat his/hercode
can be understood by each and every other developer. Though, achieving the expertise of being
understoodbyeveryotherdevelopershouldbe inthe listtobe acquired. Inlinecommentingisoftenthe
most common and most underused commenting since it provides help around particular processes or
piece of code that might be confusing later. It depends on the programmer how to implementinline
commenting. Some developerchoosestocommentontop of the line andsome choosesto commenton
the side. Although inline commenting shouldn’t be descriptive. It should be abstractive as much as
possible. The author used inline commenting like the following:
Statement ….. // f_setDBConnection() -> database_connection.cs
Commenting at the right side of the statement is more untestable as it is continuous and easy to read.
Abstractionatinline commentingismore logicalasfunctioncommentingandalsoclasscommentingisbit
descriptive.Sotoavoidredundancyof wordsitshouldbe awise choice touse abstractive approachwhile
inline commenting.
Function Comments:
Similarinpractice toClass/Page Commenting,FunctionCommentingcanprovide aquickoverview of what
a particularmethoddoes [1].The followingexample showshow touse FunctionCommentingtodiscern
what the part of the code does without digging into the code.
/*
Summary: Reads dbType to create connectionString.
Parameters: Nothing
Return: Nothing
*/
public void f_setDBConnection()
{
switch(v_dbType)
{
case "MySQL":
v_connectionString = "Server=" + v_dbSource + "; Port=9901; Database=" +
v_dbName + "; Uid=" + v_userName + "; Pwd=" + v_password + ";";
break;
}

5. 4 | P a g e
Standardized Comment Hinting [1]:
Using some common text in capital letters can help to identify certain pieces of contents within the
comments used inside any applicationwhich can be useful for someone reading or reverse engineering
your code. In addition to the revision history at the top of the document, these can help call out other
items inline.
1. HACK: Acknowledges where inelegant code was used as a work around some other problem.
2. BUG: Identifies the location of problematic piece of code.
3. TODO: Denotes unfinished piece of work.
4. FIX: Marks where something was corrected. Often the bug # would be included in this line.
Variable Names, Capitalizations and Convention:
There are quite a lot methods of notation for naming variables, functions and classes for any
application. Microsoft has provided guidance to developers working with Microsoft technologies
through a naming conventions document in MSDN library [1]. Similarly, Sun Microsystem has
provided the developers using Java with naming conventions. Below, some of the popular naming
conventions are listed:
1. Camel (or Camelback) [myVariableName]
a. First Letter Lowercase with each subsequent words first letter capitalized.
b. Standard method for Java variables.
2. Pascal [MyVariableName]
a. Each words first letter is capitalized, including the first word.
b. Standard method for .NET variables.
3. Underscore
a. Using underscore character like space [MY_Variable_Name]
b. Special cases using underscore as first value to protect namespace [_variable]
Regardless of the style chosen, it is most important for the variable to describe what it means
above all. The author used Camel font as the author was developing the system with C#. But the
author modified the Camel font for the application that was developed in Ground Effects.
Variable was declared in the following manner,
string v_appName;
Putting the character ‘v’ in front of a variable helps other developers who might need to find the
variable which was used inside the project. Also sometimes variable names has unavoidable
similarities with functions, methods and objects. To avoid this the author practiced this exact way
which will provide any developer with a better insight of the code. Similar with the declaration
process of variables, the author also declared functions, methods and also objects with a ‘f’, ‘m’
and ‘a’ character in front of them. These are as follows:
 o_logMsg (for Object)
 m_logFile (for methods)
 f_buildLogMsg (for functions)

6. 5 | P a g e
FileNames
The author used lowercase string to name files in the application. Filenames should always
describe the contents, contained within them for clarity for developers [1]. As we know filename
length limits have all been lifted out from modern operating system, it is no longer necessary to
use cryptic naming conventions. The author used the following strategy to name files inside the
application:
“log-messages.cs”
The strength to this approach is that the file can be read quite clearly without opening it top
verify its contents. In modern c#, hyphen is converted to underscore inside the class declaration
so it’s easierto read. The C# compiler indexes the above filename as ‘log_messages’(class)which
is much better than ‘logmessages’.
Bibliography
1. Web Development Naming Conventions (AF Design). Erik Giberti. September 2008.