<ol>
<li><a href="#introduction">Introduction</a>
- <li><a href="#mechanicalissues">Mechanical Source Issues
+ <li><a href="#mechanicalissues">Mechanical Source Issues</a>
<ol>
<li><a href="#sourceformating">Source Code Formatting</a>
<ol>
<ol>
<li><a href="#hl_assert">Assert Liberally</a>
<li><a href="#hl_preincrement">Prefer Preincrement</a>
+ <li><a href="#hl_avoidendl">Avoid endl</a>
<li><a href="#hl_exploitcpp">Exploit C++ to its Fullest</a>
</ol>
<li><a href="#iterators">Writing Iterators</a>
C++ doesn't do too well in the modularity department. There is no real encapsulation or data hiding (unless you use expensive protocol classes), but it is what we have to work with. When you write a public header file (in the LLVM source tree, they live in the top level "include" directory), you are defining a module of functionality.<p>
-Modules should be completely independent of each other, except for their dependence. A module is not just a class, a function, or a namespace: <a href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm">it's a collection of these</a> that defines an interface. This interface may be several functions, classes or data structures, but the important issue
s is how they work together.<p>
+Modules should be completely independent of each other, except for their dependence. A module is not just a class, a function, or a namespace: <a href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm">it's a collection of these</a> that defines an interface. This interface may be several 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>
+<!--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 have been properly added to the module header itself, and are not implicit. System headers should be included after user headers for a translation unit.<p>
<!-- _______________________________________________________________________ -->
</ul><a name="hl_assert"><h4><hr size=0>Assert Liberally</h4><ul>
-Use the "<tt>assert</tt>" function to its fullest. Check all of your preconditions and assumptions, you never know when a bug (not neccesarily even yours) might be caught early by an assertion, which reduces debugging time dramatically. The "<tt>
assert.h</tt>" header file is probably already included by the header files you are using, so it doesn't cost anything to use it.<p>
+Use the "<tt>assert</tt>" function to its fullest. Check all of your preconditions and assumptions, you never know when a bug (not neccesarily even yours) might be caught early by an assertion, which reduces debugging time dramatically. The "<tt>
<cassert></tt>" header file is probably already included by the header files you are using, so it doesn't cost anything to use it.<p>
To further assist with debugging, make sure to put some kind of error message in the assertion statement (which is printed if the assertion is tripped). This helps the poor debugging make sense of why an assertion is being made and enforced, and hopefully what to do about it. Here is one complete example:<p>
<pre>
inline Value *getOperand(unsigned i) {
- assert(i < Operands.size() && "getOperand() out of range!");
+ assert(i < Operands.size() && "getOperand() out of range!");
return Operands[i];
}
</pre>
Here are some examples:
<pre>
- assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
+ assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
- assert(idx < getNumSuccessors() && "Successor # out of range!");
+ assert(idx < getNumSuccessors() && "Successor # out of range!");
assert(V1.getType() == V2.getType() && "Constant types must be identical!");
- assert(Succ->front()->isPHINode() && "Only works on PHId BBs!");
+ assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
</pre><p>
You get the idea...<p>
The semantics of postincrement include making a copy of the value being incremented, returning it, and then preincrementing the "work value". For primitive types, this isn't a big deal... but for iterators, it can be a huge issue (for example, some iterators contains stack and set objects in them... copying an iterator could invoke the copy ctor's of these as well). In general, get in the habit of always using preincrement, and you won't have a problem.<p>
+<!-- _______________________________________________________________________ -->
+</ul><a name="hl_avoidendl"><h4><hr size=0>Avoid endl</h4><ul>
+
+The <tt>endl</tt> modifier, when used with iostreams outputs a newline to the output stream specified. In addition to doing this, however, it also flushes the output stream. In other words, these are equivalent:<p>
+
+<pre>
+ cout << endl;
+ cout << "\n" << flush;
+</pre>
+
+Most of the time, you probably have no reason to flush the output stream, so it's better to use a literal <tt>"\n"</tt>.<p>
+
+
<!-- _______________________________________________________________________ -->
</ul><a name="hl_exploitcpp"><h4><hr size=0>Exploit C++ to its Fullest</h4><ul>
public std::iterator<std::forward_iterator_tag, value_type> {
friend class container;
public:
- const value_type& operator*() const;
+ const value_type& operator*() const;
const value_type* operator->() const;
- const_iterator& operator++();
+ const_iterator& operator++();
const_iterator operator++(int);
friend bool operator==(const_iterator lhs,
const_iterator rhs);
There are normally only three member functions that need nontrivial
implementations; the rest are just boilerplate.
- const container::value_type&
+ const container::value_type&
container::const_iterator::operator*() const {
// find the element and return a reference to it
}
const container::value_type*
container::const_iterator::operator->() const {
- return &**this;
+ return &**this;
}
If there's an underlying real container, operator*() can just return a
The operator->() function is just boilerplate around a call to
operator*().
- container::const_iterator&
+ container::const_iterator&
container::const_iterator::operator++() {
// the incrementing logic goes here
return *this;
friend class container;
friend class container::const_iterator;
public:
- value_type& operator*() const;
+ value_type& operator*() const;
value_type* operator->() const;
- iterator& operator++();
+ iterator& operator++();
iterator operator++(int);
friend bool operator==(iterator lhs, iterator rhs);
friend bool operator!=(iterator lhs, iterator rhs);
friend class container;
public:
const_iterator();
- const_iterator(const iterator& i);
- const value_type& operator*() const;
+ const_iterator(const iterator& i);
+ const value_type& operator*() const;
const value_type* operator->() const;
- const_iterator& operator++();
+ const_iterator& operator++();
const_iterator operator++(int);
friend bool operator==(const_iterator lhs,
const_iterator rhs);
public std::iterator<std::bidirectional_iterator_tag, value_type> {
public:
//...
- iterator& operator--();
+ iterator& operator--();
iterator operator--(int);
//...
};
public std::iterator<std::random_access_iterator_tag, value_type> {
public:
//...
- iterator& operator+=(difference_type rhs);
- iterator& operator-=(difference_type rhs);
+ iterator& operator+=(difference_type rhs);
+ iterator& operator-=(difference_type rhs);
friend iterator operator+(iterator lhs, difference_type rhs);
friend iterator operator+(difference_type lhs, iterator rhs);
friend iterator operator-(iterator lhs, difference_type rhs);
//...
};
- container::iterator&
+ container::iterator&
container::iterator::operator+=(container::difference_type rhs) {
// add rhs to iterator position
return *this;
}
- container::iterator&
+ container::iterator&
container::iterator::operator-=(container::difference_type rhs) {
// subtract rhs from iterator position
return *this;
<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
<!-- hhmts start -->
-Last modified: Sun Jul 8 19:25:56 CDT 2001
+Last modified: Fri Jul 25 12:29:52 CDT 2003
<!-- hhmts end -->
</font>
</body></html>
projects / oota-llvm.git / blobdiff