<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/2033/1/7/_/styles/combined.css?spaceKey=TOP&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/TOP/Style+Guide">Style Guide</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~khunt">Ken Hunt</a>
</h4>
<br/>
<h4>Changes (19)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > <br> *C1.* Braces for compound statements will be on their own lines, at the same indentation level as the statement they are part of. Code and declarations in the brace-enclosed block will be indented one level from the braces. The only exception to this rule is for C\+\+ namespace and Slice module blocks; because the nesting of these scopes could change in the future, if indentation was used it would have to be changed across many source files if the nesting changed. In addition, most code is contained in at least three namespaces/modules, if not more, and indenting the code to represent this would waste a great deal of space and make the code harder to read. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{noformat} <br>namespace AsteriskSCF <br>{ <br>namespace SessionCommunications <br>{ <br>class FooClass <br>{ <br>public: <br> /** <br> * Constructor. <br> * @param defaultBar The default setting for Bar. <br> */ <br> FooClass(const Bar& defaultBar); <br> <br> /** <br> * Set new value of Bar. <br> */ <br> void setBar(const Bar& bar); <br>}; <br> <br>} // namespace SessionCommunications <br>} // namespace AsteriskSCF <br> <br>{noformat} <br></td></tr>
<tr><td class="diff-unchanged" > *C2.* Indentation: 4 spaces per level, no tabs. <br> *C3.* Interface, class and structure names will be in UpperCamelCase style. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >The following additional style guidelines will be followed in Asterisk SCF Slice definitions: <br># Empty definitions will be shown by opening and closing braces at the end of the line. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{noformat} <br>exception InvalidScaleFactor {}; <br>{noformat} <br></td></tr>
<tr><td class="diff-unchanged" ># Slice file names will end with "If.ice" (where If is for interface) so that developers in IDEs will be able to tell when they were produced generated code. (The Slice translators use the .ice filename as the basis for the generated C++ and C# filenames.) <br># {{#pragma once}} will be used for multiple-include protection. The Slice translators use the MCPP library for C-style preprocessing, which supports {{#pragma once}}. It provides a performance benefit over traditional {{#ifdef}}-based include guards in addition to being easier to read and maintain. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{noformat} <br>#pragma once <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">module AsteriskSCF <br>{ <br>module System <br>{ <br>module Time <br>{ <br>["suppress"] <br>module V1 <br>{ <br> /** <br> * String representation of the version of this interface <br> */ <br> const string Version = "V1"; <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">|!StyleGuides-Slice.png|border=1!| <br>|{center}*Figure 1. Slice Example - TimeIf.ice*{center}| <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> /** <br> * A class containing time related information. <br> */ <br> class TimeMarker <br> { <br> /** <br> * A numerical value of time. <br> */ <br> long markTime; <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h4. C\+\+ Style Guide <br>To ensure compatibility with GCC, all C\+\+ source and header files must end with a newline. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> /** <br> * The scale of the above numerical value. <br> */ <br> float scale; <br> }; <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">}; // module V1 <br>}; // module Time <br>}; // module System <br>}; // module AsteriskSCF <br> <br>{noformat} <br> <br>h4. C\+\+ Style Guide <br># To ensure compatibility with GCC, all C\+\+ source and header files must end with a newline. <br></td></tr>
<tr><td class="diff-unchanged" ># In pointer and reference declarations, the {{&}} and {{*}} modifiers should be next to the type, not the variable ({{Foo& foo}}) <br># When declaring variables, modifiers (such as {{const}} and {{auto}}) should be to written on the left side of the type ({{const Foo& foo}}). <br></td></tr>
<tr><td class="diff-changed-lines" ># Single argument {{class}} and {{struct}} constructors should always be marked *explicit*, to keep the compiler from using one in an unexpected way that keeps an error from being detected at compile time. <span class="diff-added-words"style="background-color: #dfd;">A single-argument constuctor can be used as an implicit conversion function, which not likely the intent.</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>h6. C\+\+ Header Files <br>The following additional style guidelines will be followed in C++ header files: <br># {{#pragma once}} will be used for multiple-include protection. {{#pragma once}} has been supported in GCC since version 3.4.0, and in Visual Studio since (at least) version 6. It provides a performance benefit over traditional {{#ifdef}}-based include guards in addition to being easier to read and maintain. <br></td></tr>
<tr><td class="diff-changed-lines" ># Forward declarations should be used when the code does not need the entire type declaration; the most common cases of this are pointer and reference variables, which only need the type name declared, but not its complete declaration. <span class="diff-added-words"style="background-color: #dfd;">Forward declarations allow you to minimize the number of indirect include files.</span> <br></td></tr>
<tr><td class="diff-unchanged" ># Header files should {{#include}} all other headers required to compile them; source files that *#include* a header file should not be required to know which other headers are required for it. Organize {{#include}} statements into blocks based on level. System-level headers first, library headers next (Boost, PJSIP, etc.), Asterisk SCF API headers next, and finally local headers. <br># Avoid {{using namespace;}} in header files, which could pollute the namespace inadvertently for modules which include that header file. <br># Use lower-case "m" prefix (_member_) for member variables, to avoid hiding member variables with local variables in methods. This is not done for Slice class member variables, as Slice class members are always public, since Slice classes are more analogous to C\+\+ {{struct}} than C\+\+ {{class}}. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{noformat} <br>#pragma once <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">namespace AsteriskSCF <br>{ <br>namespace SessionCommunications <br>{ <br>namespace SomeSessionManager <br>{ <br>class SomeReferencedClass; <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">|!StyleGuides-Header.png|border=1!| <br>|{center}*Figure 1. C++ Header Example*{center}| <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">/** <br> * A sample class. <br> */ <br>class SampleClass <br>{ <br>public: <br> SampleClass() {}; <br> void extractValues(const SomeReferencedClass& ref); <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">private: <br> std::string mName; <br>}; <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">} // namespace SomeSessionManager <br>} // namespace SessionCommunications <br>} // namespace AsteriskSCF <br> <br>{noformat} <br> <br></td></tr>
<tr><td class="diff-unchanged" >h6. C\+\+ Source Files <br>The following additional style guidelines will be followed in C\+\+ source (.cpp) files: <br># Organize {{#include}} statements into blocks based on level. System-level headers first, library headers next (Boost, PJSIP, etc.), Asterisk SCF API headers next, and finally local headers. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{noformat} <br>#include <Ice/Ice.h> <br>#include <IceBox/IceBox.h> <br>#include <IceStorm/IceStorm.h> <br> <br>#include <boost/shared_ptr.hpp> <br> <br>#include "ChannelService.h" <br>#include "SomeReferenceClass.h" <br>#include "SampleHeader.h" <br>{noformat} <br></td></tr>
<tr><td class="diff-unchanged" ># Flatten namespaces (if desired for convenience) here in the source file, not in header files. <br># Variables should be initialized using constructor syntax, not assignment syntax, even for Plain-Old-Data types. This is for readability and consistency, not for performance, since modern compilers will compile them to the same object code in nearly all cases. Instead of: <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">|!StyleGuides-CppFile.png|border=1!| <br>|{center}*Figure 1. C\+\+ Source Example*{center}| <br> <br></td></tr>
<tr><td class="diff-unchanged" >h4. Editor setup <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This page defines a Style Guide for developing Slice and C++ source code.</td></tr></table></div>
<div>
<ul>
<li><a href='#StyleGuide-CommonRules'>Common Rules</a></li>
<li><a href='#StyleGuide-SliceStyleGuide'>Slice Style Guide</a></li>
<li><a href='#StyleGuide-C%5C%5CStyleGuide'>C++ Style Guide</a></li>
<ul>
<li><a href='#StyleGuide-C%5C%5CHeaderFiles'>C++ Header Files</a></li>
<li><a href='#StyleGuide-C%5C%5CSourceFiles'>C++ Source Files</a></li>
</ul>
<li><a href='#StyleGuide-Editorsetup'>Editor setup</a></li>
<ul>
<li><a href='#StyleGuide-Emacs'>Emacs</a></li>
</ul>
</ul></div>
<h4><a name="StyleGuide-CommonRules"></a>Common Rules</h4>
<p>The following style guidelines will be followed for both Slice and C++ code:</p>
<p> <b>C1.</b> Braces for compound statements will be on their own lines, at the same indentation level as the statement they are part of. Code and declarations in the brace-enclosed block will be indented one level from the braces. The only exception to this rule is for C++ namespace and Slice module blocks; because the nesting of these scopes could change in the future, if indentation was used it would have to be changed across many source files if the nesting changed. In addition, most code is contained in at least three namespaces/modules, if not more, and indenting the code to represent this would waste a great deal of space and make the code harder to read.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>namespace AsteriskSCF
{
namespace SessionCommunications
{
class FooClass
{
public:
/**
* Constructor.
* @param defaultBar The default setting for Bar.
*/
FooClass(const Bar& defaultBar);
/**
* Set new value of Bar.
*/
void setBar(const Bar& bar);
};
} // namespace SessionCommunications
} // namespace AsteriskSCF
</pre>
</div></div>
<p> <b>C2.</b> Indentation: 4 spaces per level, no tabs.<br/>
<b>C3.</b> Interface, class and structure names will be in UpperCamelCase style. <br/>
<b>C4.</b> Function, operation and member variable names will follow lowerCamelCase style.<br/>
<b>C5.</b> Comments will follow Doxygen (Javadoc form) guidelines. For Slice this will apply to interface, class and struct definitions, and all operations. For C++, this will apply to classes and operations. All other comments will follow C++ standard convention, which is for "//" comments to be used except for lengthy multi-line comments. <br/>
<b>C6.</b> Comment the end of namespace scopes (or any code blocks long enough that would likely not be entirely visible on a typical screen) to improve maintainability / readability. <br/>
<b>C7.</b> All comments shall be in the English language.</p>
<h4><a name="StyleGuide-SliceStyleGuide"></a>Slice Style Guide</h4>
<p>The following additional style guidelines will be followed in Asterisk SCF Slice definitions:</p>
<ol>
<li>Empty definitions will be shown by opening and closing braces at the end of the line.
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>exception InvalidScaleFactor {};
</pre>
</div></div></li>
<li>Slice file names will end with "If.ice" (where If is for interface) so that developers in IDEs will be able to tell when they were produced generated code. (The Slice translators use the .ice filename as the basis for the generated C++ and C# filenames.)</li>
<li><tt>#pragma once</tt> will be used for multiple-include protection. The Slice translators use the MCPP library for C-style preprocessing, which supports <tt>#pragma once</tt>. It provides a performance benefit over traditional <tt>#ifdef</tt>-based include guards in addition to being easier to read and maintain.
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>#pragma once
module AsteriskSCF
{
module System
{
module Time
{
["suppress"]
module V1
{
/**
* String representation of the version of this interface
*/
const string Version = "V1";
/**
* A class containing time related information.
*/
class TimeMarker
{
/**
* A numerical value of time.
*/
long markTime;
/**
* The scale of the above numerical value.
*/
float scale;
};
}; // module V1
}; // module Time
}; // module System
}; // module AsteriskSCF
</pre>
</div></div></li>
</ol>
<h4><a name="StyleGuide-C%5C%5CStyleGuide"></a>C++ Style Guide</h4>
<ol>
<li>To ensure compatibility with GCC, all C++ source and header files must end with a newline.</li>
<li>In pointer and reference declarations, the <tt>&</tt> and <tt>*</tt> modifiers should be next to the type, not the variable (<tt>Foo& foo</tt>)</li>
<li>When declaring variables, modifiers (such as <tt>const</tt> and <tt>auto</tt>) should be to written on the left side of the type (<tt>const Foo& foo</tt>).</li>
<li>Single argument <tt>class</tt> and <tt>struct</tt> constructors should always be marked <b>explicit</b>, to keep the compiler from using one in an unexpected way that keeps an error from being detected at compile time. A single-argument constuctor can be used as an implicit conversion function, which not likely the intent.</li>
</ol>
<h6><a name="StyleGuide-C%5C%5CHeaderFiles"></a>C++ Header Files</h6>
<p>The following additional style guidelines will be followed in C++ header files:</p>
<ol>
<li><tt>#pragma once</tt> will be used for multiple-include protection. <tt>#pragma once</tt> has been supported in GCC since version 3.4.0, and in Visual Studio since (at least) version 6. It provides a performance benefit over traditional <tt>#ifdef</tt>-based include guards in addition to being easier to read and maintain.</li>
<li>Forward declarations should be used when the code does not need the entire type declaration; the most common cases of this are pointer and reference variables, which only need the type name declared, but not its complete declaration. Forward declarations allow you to minimize the number of indirect include files.</li>
<li>Header files should <tt>#include</tt> all other headers required to compile them; source files that <b>#include</b> a header file should not be required to know which other headers are required for it. Organize <tt>#include</tt> statements into blocks based on level. System-level headers first, library headers next (Boost, PJSIP, etc.), Asterisk SCF API headers next, and finally local headers.</li>
<li>Avoid <tt>using namespace;</tt> in header files, which could pollute the namespace inadvertently for modules which include that header file.</li>
<li>Use lower-case "m" prefix (<em>member</em>) for member variables, to avoid hiding member variables with local variables in methods. This is not done for Slice class member variables, as Slice class members are always public, since Slice classes are more analogous to C++ <tt>struct</tt> than C++ <tt>class</tt>.
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>#pragma once
namespace AsteriskSCF
{
namespace SessionCommunications
{
namespace SomeSessionManager
{
class SomeReferencedClass;
/**
* A sample class.
*/
class SampleClass
{
public:
SampleClass() {};
void extractValues(const SomeReferencedClass& ref);
private:
std::string mName;
};
} // namespace SomeSessionManager
} // namespace SessionCommunications
} // namespace AsteriskSCF
</pre>
</div></div></li>
</ol>
<h6><a name="StyleGuide-C%5C%5CSourceFiles"></a>C++ Source Files</h6>
<p>The following additional style guidelines will be followed in C++ source (.cpp) files:</p>
<ol>
<li>Organize <tt>#include</tt> statements into blocks based on level. System-level headers first, library headers next (Boost, PJSIP, etc.), Asterisk SCF API headers next, and finally local headers.
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>#include <Ice/Ice.h>
#include <IceBox/IceBox.h>
#include <IceStorm/IceStorm.h>
#include <boost/shared_ptr.hpp>
#include "ChannelService.h"
#include "SomeReferenceClass.h"
#include "SampleHeader.h"
</pre>
</div></div></li>
<li>Flatten namespaces (if desired for convenience) here in the source file, not in header files.</li>
<li>Variables should be initialized using constructor syntax, not assignment syntax, even for Plain-Old-Data types. This is for readability and consistency, not for performance, since modern compilers will compile them to the same object code in nearly all cases. Instead of:
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>int x = 1;
string str = "This is a string.";
ProxyPtr proxy = 0;
</pre>
</div></div>
<p>use:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>int x(1);
string str("This is a string.");
ProxyPtr proxy(0);
</pre>
</div></div></li>
<li>Write function calls with no whitespace between the function name and the opening parenthesis, or around the parentheses. The only whitespace should be following any commas that separate arguments, like this:
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>doOperation("xyz", 2, fooPtr);
</pre>
</div></div></li>
<li>Don't format statements (<tt>for</tt>, <tt>if</tt>, <tt>switch</tt>, <tt>while</tt>, etc.) as if they were function calls; a single space should appear after the keyword, like this:
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>if ((x + 1) > 100)
{
return y;
}
for (x = 0; x++; x < z)
{
y *= 3;
}
</pre>
</div></div></li>
<li>Compound statements must always be enclosed in braces, even if the block contains only one statement. This rule helps to avoid unexpected execution paths when code is modified for debugging purposes (or any other reason). Instead of this:
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>if (x > 5)
return y;
while (z > 4)
z /= 2;
</pre>
</div></div>
<p>use this:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>if (x > 5)
{
return y;
}
while (z > 4)
{
z /= 2;
}
</pre>
</div></div></li>
</ol>
<h4><a name="StyleGuide-Editorsetup"></a>Editor setup</h4>
<h6><a name="StyleGuide-Emacs"></a>Emacs</h6>
<p>Save a copy of the attached file <tt><a href="/wiki/download/attachments/3702855/asterisk-scf-style.el?version=2&modificationDate=1291219045376">asterisk-scf-style.el</a></tt> into your <tt>site-lisp</tt> directory. Make sure you have the following in your <tt>.emacs</tt> files.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Various flavors of Emacs store startup scripts in different places. Check the documentation for your distribution if .emacs doesn't seem quite right for you.</td></tr></table></div>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>(require 'asterisk-scf-style)
;; Treat .h files as C++ files
(add-to-list 'auto-mode-alist '("\\.h\\'" . c++-mode))
;; You may want to merge this with existing configuration in your custom-set-variables block
(setq indent-tabs-mode nil
require-final-newline t
show-trailing-whitespace t
c-default-style '((c-mode . "asterisk-scf") (c++-mode . "asterisk-scf"))
)
</pre>
</div></div>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;">
<a href="https://wiki.asterisk.org/wiki/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/TOP/Style+Guide">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=3702855&revisedVersion=46&originalVersion=45">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/Style+Guide?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>