[b4a227]: community / coding_style / index.shtml Maximize Restore History

Download this file

index.shtml    214 lines (149 with data), 9.7 kB

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Hugin - Coding Style Guide</title>
<style media="screen" type="text/css" title="Screen style sheet">
@import url(/css/normal.css);
</style>
</head>
<body>

<!--#include virtual="/ssi/menu.shtml"-->
<div class="content">
<h1>Hugin Coding Style Guide</h1>

<p>Consistent application of a style makes life easier for everybody. You'll find other people's code more readable, and they will find your code more readable.  While nobody will tap on your fingers for not following these conventions to the letter, it is highly recommended that you familiarize with them and follow them.</p>

<h2>History and Status of this Document</h2>

<p>This document started from a <a href="http://groups.google.com/group/hugin-ptx//t/804cd02427aa3d07/" target="_blank">discussion</a> on coding style and consistency.  It is currently just a collection of the wisdom and opinion of Hugin contributors and we won't do hard enforcement / policing, but it would be nice if we could all stick to the same convention and make the code more readable and manageable for everyobdy.</p>

<h2>Naming Conventions</h2>

<ul>
<li>Names should be clear and descriptive. No contractions, with a few listed below.</li>
<li>In general, we prefer CamelCase over underscore_insertions.</li>
<li>LeadingCaps (capitalized first letter of a name) should be used only for classes, structs, and typedefs.</li>
<li>Variables and functions should not have an initial capital. (although Ryan was suggesting that public function be LeadingCaps and private ones not).</li>
<li>Private variables should be prefixed with <i>m_</i>. Many (but not all) private variables are currently prefixed.</li>
<li>Constants are ALL_CAPS with underscore insertions.</li>
<li>Where there are contractions, they should be used consistently across the code base. Make yourself familiar with the list.  There are some hisotrical exceptions, e.g. Pano instead of Panorama.  Any more exceptions?</li>
</ul>

<h3>Contraction Lists</h3>
<ul>
<li>Pano: for panorama</li>
<li>FOV: for Field of View</li>
<li>ROI: for Region of Interest</li>
</ul>

<p>The list is incomplete.</p>

<h2>Metadata</h2>

<h3>Documentation</h3>

<p>Document your code (or the code you are reading and understanding) with <a href="http://www.doxygen.org" target="_blank">doxygen</a>. Doxygen is a useful tool and can also be used to create other documentation that just class interface descriptions. It works by prefixing the function prototypes with a special comment.  Pablo usually puts the documentation in the header files.</p>

<p>The basic usage is very javadoc like:</p>

<pre>
/** One sentence class description
 *
 *  more detailed description
 *
 *  @todo pet the cat more often
 *  @bug  might scratch if annoyed
 */
class Cat
{
public:
    /** hunt food
     *
     *  @param prey type of animals that we should hunt
     *  @return true if the cat is sated
     */
    bool HuntFood(Prey prey);

}
</pre>

<h3>Identify Work in Progress</h3>

<ul>
<li>Maintain the <i>@todo</i> and <i>@bug</i> sections of doxygen. They are summarized and listed in the automatically generated documentation's <a href="http://hugin.sourceforge.net/docs/html/todo.shtml" target="_blank">todo</a> and <a href="http://hugin.sourceforge.net/docs/html/bug.shtml" target="_blank">bugs</a> lists.</li>
<li>For small things inside the code, put <i>// FIXME</i> or  <i>// TODO</i> comments - they will be automatically highlighted by gedit and other editors, and will be easily searchable with grep.</li>
</ul>

<h3>Comments</h3>

<p>Comments and inline-documentation are always welcome, please give them lines of their own and don't append them to existing code:</p>

<pre>
exit(); do_stuff(); //Don't do this
</pre>

<h3>File Names</h3>

<p>Try to keep one class per file, and give the file a meaningful name in CamelCase.</p>


<h2>Code Layout</h2>

<p>Spacing and indentation contirbute a lot to the readability of the code. Use them liberally.</p>

<h3>Bracing</h3>

<p>There are many different indentation styles. <a href="http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS" target="_blank">1TBS</a> (like the Linux Kernel) is the preferred one. However it is more important to keep consistency within a file, so if you are editing a file with a different convention, adopt it (or read the clean up section of this style guide).</p>

<pre>
if (1 == 0) {
    printf("never");
} else {
    printf("ever");
}
</pre>


<h3>Tabulation</h3>

<p>Use spaces instead of tabulators (to maintain consistency across editors).  The preferred indentation is four spaces for one tab, but most important is to keep consistency within a single file.</p>

<h3>Spacing</h3>

<p>I would not go into that much detail. or maybe we should adopt/adapt a strict coding guide like <a href="http://www.blender.org/documentation/intranet/conventions/codingstyleguide.html" target="_blank">Blender</a>?</p>

<h3>Line Ends</h3>

<p>Set your editor to Unix-style line ending (LF) - not Windows' LF+CR.  Or if you are on Windows, use the Mercurial <a href="http://mercurial.selenic.com/wiki/EolExtension" target="_blank">EOL</a> extension.</p>

<p>To prevent accidentally committing a file with Windows line endings, you can add the following snippet to your global .hgrc or mercurial.ini file:</p>

<pre>
[hooks]
pretxncommit.crlf = python:hgext.win32text.forbidcrlf
</pre>

<h3>Character Set</h3>

<p>Ideally we are striving to use UTF-8, but because Windows has issue dealing with it, the wxWidgets XRC ressources are ISO-8859-1.</p>

<h3>Multiple Statements on one Line</h3>

<p>Avoid multiple statements on one line, it makes the code harder to read.</p>

<h3>Line Width</h3>

<p>Try to keep line width below 80 characters.</p>

<h2>Repository</h2>

<h3>Commits</h3>

<p>It is tempting to clean up old code while fixing bugs or adding new code. Please don't - it makes the committ (diff!) much more difficult to read / understand.  Keep style clean up committs separated and mention them as such in the log message.</p>

<p>It is important that nobody goes around changing existing code to suit without thinking about it first - We have several branches waiting to be merged, changing the amount of whitespace makes that difficult, and splitting or joining lines of code makes it enormously more so.</p>

<h3>Work in Progress</h3>

<p>If something needs work, mark it with a <b>// FIXME</b> or <b>// TODO</b> comment so that a grep will reveal places that needs attention. Gedit automatically highlights TODO and FIXME.</p>

<p>For minor changes, feel free to commit directly into the default codeline.  For everything else, branch out.  Branches are cheap.</p>

<h3>Strings for Translation</h3>

<p>Release branches are string-frozen.  Strings for translation are updated prior to branching and in principle no new string shall be added to a release branch.  An exception may be requested if the underlying motive is important enough.  The request must receive the support of a significant majority of developers (coders, builders, translators) to be granted.  Silence is interpreted as supportive of the request.</p>

<h3>API stability</h3>

<p>Release branches are frozen regarding classes/function/namespace names and functions parameters.  An exception may be requested if the underlying motive is important enough.  The request must receive the support of a significant majority of developers (coders and scripters) to be granted.  Silence is interpreted as supportive of the request.</p>

<h2>License</h2>

<ul>
<li>Make sure all new files added to the repository come with a license.</li>
<li>Hugin is historically licensed GPL 2 or later.</li>
<li>Best is to choose the same license, or a compatible one.</li>
<li>If you want to license under the GPL 2 or later, just copy and the text below into a comment at the beginning of each of your new files.</li>
</ul>

<pre>
/*
** &lt;one line to give the program's name and a brief idea of what it does.&gt;
** Copyright (C) &lt;year&gt;  &lt;name of author&gt;
**
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU General Public License as published by
** the Free Software Foundation, either version 2 of the License, or
** (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU General Public License for more details.
**
** You should have received a copy of the GNU General Public License
** along with this program.  If not, see &lt;http://www.gnu.org/licenses/&gt;.
*/
</pre>

<h2>Goto / Case Labels</h2>

<p>Try to write code that is linear to read and does not jump all over the place too much.</p>

<h2>Compilation Warnings and Diagnostic Output</h2>

<p>Try to prevent compiler warnings.</p>

<p>Encapsulate diagnostic output in a condition and commit it so that by default there is no diagnostic output.  Consider that some CMake output must be clicked away on Windows while it is just an extra line of display in Linux.</p>

<p>&nbsp;</p>
<p>Return to <a href="/">main page</a>.</p>

<p><small>
<ul>
<li>First <a href="http://hugin.hg.sourceforge.net/hgweb/hugin/hugin-web/rev/6c656d1ba5ce" target="_blank">drafted February 14, 2011 by <a href="http://www.levy.ch/" target="_blank">Yuval Levy</a></li>
<li>Last changed: February 14, 2011 by Yuval Levy</li>
</ul>
</small></p>

</div>
</body>
</html>