<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/2030/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/~dlee">David M. Lee</a>
</h4>
<div id="versionComment">
<b>Comment:</b>
Moved warning about using volatile to C++ Best Practices.<br />
</div>
<br/>
<h4>Changes (1)</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" ># In pointer and reference declarations, the {{&}} and {{*}} should be next to the type, not the variable ({{Foo& foo}}) <br># When declaring {{const}} pointer and references, the {{const}} modifier should be to the left of the type ({{const Foo& foo}}). <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">** Avoid "volatile" or any other platform/compiler specific idiosyncrasies. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h6. C++ Header Files <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-CStyleGuide'>C++ Style Guide</a></li>
<ul>
<li><a href='#StyleGuide-CHeaderFiles'>C++ Header Files</a></li>
<li><a href='#StyleGuide-CSourceFiles'>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> Opening braces will be on next line, at same level of indentation as previous line. In general, all code blocks are indented. Namespace blocks are not indented for maintenance reasons. (Namespace nesting may be altered, which would require altering indentation for each such change.) <br/>
<b>C2.</b> Indentation: 4 spaces, no tabs.<br/>
<b>C3.</b> Interface, class and structure names will be in UpperCamelCase style. <br/>
<b>C4.</b> 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 development of Asterisk SCF Slice definitions:</p>
<ol>
<li>Empty definitions will be shown by opening and closing braces at the end of the line.</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 are in generated code. (The slice translator uses the .ice filename as the basis for the C++ and C# filenames.)</li>
<li><b>#pragma once</b> will be used for multiple-include protection. <b>#pragma once</b> has been supported in GCC since version 3.4.0, and in Visual Studio since (at least) version 6. In addition, it provides a performance benefit over traditional <b>#ifdef</b>-based include guards in addition to being easier to read and maintain.</li>
</ol>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'><span class="image-wrap" style=""><img src="/wiki/download/attachments/3702855/StyleGuides-Slice.png?version=4&modificationDate=1291244720178" style="border: 1px solid black" /></span></td>
</tr>
<tr>
<td class='confluenceTd'><div class="" align="center"><b>Figure 1. Slice Example - TimeIf.ice</b></div>
</td>
</tr>
</tbody></table>
</div>
<h4><a name="StyleGuide-CStyleGuide"></a>C++ Style Guide</h4>
<p>To insure compatibility with gcc, all C++ source and header files must end with a blank line. </p>
<ol>
<li>In pointer and reference declarations, the <tt>&</tt> and <tt>*</tt> should be next to the type, not the variable (<tt>Foo& foo</tt>)</li>
<li>When declaring <tt>const</tt> pointer and references, the <tt>const</tt> modifier should be to the left of the type (<tt>const Foo& foo</tt>).</li>
</ol>
<h6><a name="StyleGuide-CHeaderFiles"></a>C++ Header Files</h6>
<p>The following additional guidelines will apply to C++ header files:</p>
<ol>
<li><b>#pragma once</b> will be used for multiple-include protection. <b>#pragma once</b> has been supported in GCC since version 3.4.0, and in Visual Studio since (at least) version 6. In addition, it provides a performance benefit over traditional <b>#ifdef</b>-based include guards in addition to being easier to read and maintain.</li>
<li>Forward references for types whose definitions can be deferred will be used to reduce including additional files when practical. For example, when only a pointer or reference to a type is required, the full definition of the type is not necessary. (But header files should be usable without requiring the .CPP file to include additional files.)</li>
<li>Avoid "using namespace" in header files, which could flatten the namespace inadvertently for many other modules.</li>
<li>Use lower-case "m" prefix (for member) for member variables, to avoid hiding member variable with local variables in methods. This is not done for Slice class member variables, as Slice class members are always public, and more analogous to a C++ struct than a C++ class.</li>
</ol>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'><span class="image-wrap" style=""><img src="/wiki/download/attachments/3702855/StyleGuides-Header.png?version=5&modificationDate=1291244917853" style="border: 1px solid black" /></span></td>
</tr>
<tr>
<td class='confluenceTd'><div class="" align="center"><b>Figure 1. C++ Header Example</b></div>
</td>
</tr>
</tbody></table>
</div>
<h6><a name="StyleGuide-CSourceFiles"></a>C++ Source Files</h6>
<p>The following style guidelines will apply to C++ source (.cpp) files:</p>
<ol>
<li>Organize include statements into blocks based on level. Highest level includes first, specific packages, and finally our own.</li>
<li>Flatten namespaces (if desired for convenience) here in the CPP file rather than in the headers.</li>
</ol>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'><span class="image-wrap" style=""><img src="/wiki/download/attachments/3702855/StyleGuides-CppFile.png?version=5&modificationDate=1291245050440" style="border: 1px solid black" /></span></td>
</tr>
<tr>
<td class='confluenceTd'><div class="" align="center"><b>Figure 1. C++ Source Example</b></div>
</td>
</tr>
</tbody></table>
</div>
<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=33&originalVersion=32">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>