<ol>
<li><a href="#scf_commenting">Commenting</a>
<li><a href="#scf_commentformat">Comment Formatting</a>
+ <li><a href="#scf_includes">#include Style</a>
<li><a href="#scf_codewidth">Source Code Width</a>
<li><a href="#scf_spacestabs">Use Spaces Instead of Tabs</a>
<li><a href="#scf_indentation">Indent Code Consistently</a>
//===----------------------------------------------------------------------===//
</pre>
-A few things to note about this particular format. The "<tt>-*- C++ -*-</tt>" string on the first line is there to tell Emacs that the source file is a C++ file, not a C file (Emacs assumes .h files are C files by default [Note that tag this is not nec
cesary in .cpp files]). The name of the file is also on the first line, along with a very short description of the purpose of the file. This is important when printing out code and flipping though lots of pages.<p>
+A few things to note about this particular format. The "<tt>-*- C++ -*-</tt>" string on the first line is there to tell Emacs that the source file is a C++ file, not a C file (Emacs assumes .h files are C files by default [Note that tag this is not nec
essary in .cpp files]). The name of the file is also on the first line, along with a very short description of the purpose of the file. This is important when printing out code and flipping though lots of pages.<p>
The main body of the description does not have to be very long in most cases. Here it's only two lines. If an algorithm is being implemented or something tricky is going on, a reference to the paper where it is published should be included, as well as any notes or "gotchas" in the code to watch out for.<p>
<h4><li>Method information</h4>
-Methods defined in a class (as well as any global functions) should also be documented properly. A quick note about what it does any a description of the borderline behaviour is all that is nec
cesary here (unless something particularly tricky or insideous is going on). The hope is that people can figure out how to use your interfaces without reading the code itself... that is the goal metric.<p>
+Methods defined in a class (as well as any global functions) should also be documented properly. A quick note about what it does any a description of the borderline behaviour is all that is nec
essary here (unless something particularly tricky or insideous is going on). The hope is that people can figure out how to use your interfaces without reading the code itself... that is the goal metric.<p>
Good things to talk about here are what happens when something unexpected happens: does the method return null? Abort? Format your hard disk?<p>
</ol>
To comment out a large block of code, use <tt>#if 0</tt> and <tt>#endif</tt>. These nest properly and are better behaved in general than C style comments.<p>
+<!-- _______________________________________________________________________ -->
+</ul><a name="scf_includes"><h4><hr size=0>#include Style</h4><ul>
+
+Immediately after the <a href="#scf_commenting">header file comment</a> (and
+include guards if working on a header file), the <a
+href="hl_dontinclude">minimal</a> list of #includes required by the file should
+be listed. We prefer these #includes to be listed in this order:<p>
+
+<ol>
+<li><a href="#mmheader">Main Module header</a>
+<li><a href="#hl_privateheaders">Local/Private Headers</a>
+<li>llvm/*
+<li>llvm/Analysis/*
+<li>llvm/Assembly/*
+<li>llvm/Bytecode/*
+<li>llvm/CodeGen/*
+<li>...
+<li>Support/*
+<li>Config/*
+<li>System #includes
+</ol>
+
+... and each catagory should be sorted by name.<p>
+
+<a name="mmheader">The "Main Module Header" file applies to .cpp file which
+implement an interface defined by a .h file. This #include should always be
+included <b>first</b> regardless of where it lives on the file system. By
+including a header file first in the .cpp files that implement the interfaces,
+we ensure that the header does not have any hidden dependencies which are not
+explicitly #included in the header, but should be. It is also a form of
+documentation in the .cpp file to indicate where the interfaces it implements
+are defined.<p>
+
<!-- _______________________________________________________________________ -->
</ul><a name="scf_codewidth"><h4><hr size=0>Source Code Width</h4><ul>
functions, classes or data structures, but the important issue is how they work
together.<p>
-<!--One example of this is the <tt>llvm/include/llvm/CFG.h</tt> file. It
-defines a collection of global functions, template classes, and member functions
-that are syntactically unrelated to each other. Semantically, however, they all
-provide useful functionality for operating on a CFG, and so they are bound
-together.<p> -->
-
In general, a module should be implemented with one or more <tt>.cpp</tt> files.
Each of these <tt>.cpp</tt> files should include the header that defines their
interface first. This ensure that all of the dependences of the module header
you actually implement it. Typically it looks something like this
(I'll start with the const-iterator-only situation):
- #include <iterator>
+ #include <iterator>
class container {
public:
typedef something_or_other value_type;
class const_iterator:
- public std::iterator<std::forward_iterator_tag, value_type> {
+ public std::iterator<std::forward_iterator_tag, value_type> {
friend class container;
public:
const value_type& operator*() const;
typedef something_or_other value_type;
class const_iterator;
class iterator:
- public std::iterator<std::forward_iterator_tag, value_type> {
+ public std::iterator<std::forward_iterator_tag, value_type> {
friend class container;
friend class container::const_iterator;
public:
//...
};
class const_iterator:
- public std::iterator<std::forward_iterator_tag, value_type> {
+ public std::iterator<std::forward_iterator_tag, value_type> {
friend class container;
public:
const_iterator();
iterators:
class iterator:
- public std::iterator<std::bidirectional_iterator_tag, value_type> {
+ public std::iterator<std::bidirectional_iterator_tag, value_type> {
public:
//...
iterator& operator--();
Random access iterators add several more member and friend functions:
class iterator:
- public std::iterator<std::random_access_iterator_tag, value_type> {
+ public std::iterator<std::random_access_iterator_tag, value_type> {
public:
//...
iterator& operator+=(difference_type rhs);
friend iterator operator+(difference_type lhs, iterator rhs);
friend iterator operator-(iterator lhs, difference_type rhs);
friend difference_type operator-(iterator lhs, iterator rhs);
- friend bool operator<(iterator lhs, iterator rhs);
- friend bool operator>(iterator lhs, iterator rhs);
- friend bool operator<=(iterator lhs, iterator rhs);
- friend bool operator>=(iterator lhs, iterator rhs);
+ friend bool operator<(iterator lhs, iterator rhs);
+ friend bool operator>(iterator lhs, iterator rhs);
+ friend bool operator<=(iterator lhs, iterator rhs);
+ friend bool operator>=(iterator lhs, iterator rhs);
//...
};
// calculate distance between iterators
}
- bool operator<(container::iterator lhs, container::iterator rhs) {
+ bool operator<(container::iterator lhs, container::iterator rhs) {
// perform less-than comparison
}
- bool operator>(container::iterator lhs, container::iterator rhs) {
- return rhs < lhs;
+ bool operator>(container::iterator lhs, container::iterator rhs) {
+ return rhs < lhs;
}
- bool operator<=(container::iterator lhs, container::iterator rhs) {
- return !(rhs < lhs);
+ bool operator<=(container::iterator lhs, container::iterator rhs) {
+ return !(rhs < lhs);
}
- bool operator>=(container::iterator lhs, container::iterator rhs) {
- return !(lhs < rhs);
+ bool operator>=(container::iterator lhs, container::iterator rhs) {
+ return !(lhs < rhs);
}
Four of the functions (operator+=(), operator-=(), the second
-operator-(), and operator<()) are nontrivial; the rest are
+operator-(), and operator<()) are nontrivial; the rest are
boilerplate.
One feature of the above code that some experts may disapprove of is
STL-like containers and iterators.
--
-Ross Smith <ross.s@ihug.co.nz> The Internet Group, Auckland, New Zealand
+Ross Smith <ross.s@ihug.co.nz> The Internet Group, Auckland, New Zealand
</pre>
<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
<!-- hhmts start -->
-Last modified: Fri Jul 25 12:29:52 CDT 2003
+Last modified: Thu Aug 7 16:44:33 CDT 2003
<!-- hhmts end -->
</font>
</body></html>
projects / oota-llvm.git / blobdiff