Export (0) Print
Expand All

Coding Style Conventions

Coding style conventions are used in this sample series to aid clarity and consistency. The "Hungarian" notation conventions are used. These have become a common coding practice in Win32 programming. They include variable prefix notations that give to variable names a suggestion of the type of the variable.

The following table lists common prefixes.

PrefixDescription
aArray
bBOOL (int)
cChar
cbCount of bytes
crColor reference value
cxCount of x (short)
dwDWORD (unsigned long)
fFlags (usually multiple bit values)
fnFunction
g_Global
hHandle
iInteger
lLong
lpLong pointer
m_Data member of a class
nShort int
pPointer
sString
szZero terminated String
tmText metric
uUnsigned int
ulUnsigned long (ULONG)
wWORD (unsigned short)
x,yx, y coordinates (short)

 

These are often combined, as in the following.

Prefix combination Description
pszMyString A pointer to a string.
m_pszMyStringA pointer to a string that is a data member of a class.

 

Other conventions are listed in the following table.

ConventionDescription
CMyClassPrefix 'C' for C++ class names.
COMyObjectClassPrefix 'CO' for COM object class names.
CFMyClassFactoryPrefix 'CF' for COM class factory names.
IMyInterfacePrefix 'I' for COM interface class names.
CImpIMyInterfacePrefix 'CImpI' for COM interface implementation classes.

 

Some consistent conventions for comment header blocks are used in this sample series as follows.

File Header

/*+===================================================================
  File:      MYFILE.EXT

  Summary:   Brief summary of the file contents and purpose.

  Classes:   Classes declared or used (in source files).

  Functions: Functions exported (in source files).

  Origin:    Indications of where content may have come from. This
             is not a change history but rather a reference to the
             editor-inheritance behind the content or other
             indications about the origin of the source.

----------------------------------------------------------------------
  Copyright and Legal notices.
  Copyright and Legal notices.
===================================================================+*/

Plain Comment Block

/*--------------------------------------------------------------------
  Plain block of comment text that usually takes several lines.
  Plain block of comment text that usually takes several lines.
--------------------------------------------------------------------*/

Class Declaration Header

/*C+C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C
  Class:    CMyClass

  Summary:  Short summary of purpose and content of CMyClass.
            Short summary of purpose and content of CMyClass.

  Methods:  MyMethodOne
              Short description of MyMethodOne.
            MyMethodTwo
              Short description of MyMethodTwo.
            CMyClass
              Constructor.
            ~CMyClass
              Destructor.
C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C-C*/

Class Method Definition Header

/*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  Method:   CMyClass::MyMethodOne

  Summary:  Short summary of purpose and content of MyMethodOne.
            Short summary of purpose and content of MyMethodOne.

  Args:     MYTYPE MyArgOne
              Short description of argument MyArgOne.
            MYTYPE MyArgTwo
              Short description of argument MyArgTwo.

  Modifies: [list of member data variables modified by this method].

  Returns:  MYRETURNTYPE
              Short description of meaning of the return type values.
M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/

Unexported or Local Function

/*F+F+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  Function: MyLocalFunction

  Summary:  What MyLocalFunction is for and what it does.

  Args:     MYTYPE MyFunctionArgument1
              Description.
            MYTYPE MyFunctionArgument1
              Description.

  Returns:  MyReturnType
              Description.
-----------------------------------------------------------------F-F*/

Exported Function Definition Header

/*F+F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F
  Function: MyFunction

  Summary:  What MyFunction is for and what it does.

  Args:     MYTYPE MyFunctionArgument1
              Description.
            MYTYPE MyFunctionArgument1
              Description.

  Returns:  MyReturnType
              Description.
F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F-F*/

COM Interface Declaration Header

/*I+I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I
  Interface: IMyInterface

  Summary:   Short summary of what features the interface can bring to
             a COM Component.

  Methods:   MYTYPE MyMethodOne
               Description.
             MYTYPE MyMethodTwo
               Description.
I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I-I*/

COM Object Class Declaration Header

/*O+O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O
  ObjectClass: COMyCOMObject

  Summary:     Short summary of purpose and content of this object.

  Interfaces:  IUnknown
                 Standard interface providing COM object features.
               IMyInterfaceOne
                 Description.
               IMyInterfaceTwo
                 Description.

  Aggregation: [whether this COM Object is aggregatable or not]
O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O-O*/

All of these comment block conventions have consistent beginning and ending token strings. This consistency supports automatic processing of the headers in some fashion. For example, AWK scripts can be written to filter the function headers into a separate text file that can then serve as the basis for a specification document. Similarly, tools like the unsupported AUTODUCK utility (currently available on the Microsoft Developer Network Development Library CD-ROM) can be used to process the comment blocks in these headers.

The following table lists beginning and ending token strings used in sample tutorials.

TokenDescription
/*+File Header Begin
+*/File Header End
/*-Plain comment block Header Begin
-*/Plain comment block Header End
/*CClass Header Begin
C*/Class Header End
/*MMethod Header Begin
M*/Method Header End
/*FFunction Header Begin
F*/Function Header End
/*IInterface Header Begin
I*/Interface Header End
/*OCOM Object Class Header Begin
O*/COM Object Class Header End

 

These headers can also be used as visual cues for rapid scanning of source files. They also provide convenience for rapidly getting to some source location if you set up search strings in your editor and then 'repeat last search' to quickly locate these headers.

For example, the search string "M+M" will locate the start of method headers, and "M-M" will locate the beginning of the actual method definition/implementation code.

 

 

Community Additions

ADD
Show:
© 2015 Microsoft