diff options
author | Chris Lattner <sabre@nondot.org> | 2012-03-16 22:34:37 +0000 |
---|---|---|
committer | Chris Lattner <sabre@nondot.org> | 2012-03-16 22:34:37 +0000 |
commit | 748c1ec713bb592d44827d08c40876cec3ecc644 (patch) | |
tree | 94c44ead5ed4561aa3fd53c4535a61b4d1664515 /docs | |
parent | 11d5dc3d50217711462b453ca9592e39d0c879e7 (diff) | |
download | external_llvm-748c1ec713bb592d44827d08c40876cec3ecc644.zip external_llvm-748c1ec713bb592d44827d08c40876cec3ecc644.tar.gz external_llvm-748c1ec713bb592d44827d08c40876cec3ecc644.tar.bz2 |
clarify the coding standards a bit.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@152957 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs')
-rw-r--r-- | docs/CodingStandards.html | 64 |
1 files changed, 32 insertions, 32 deletions
diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index a5f6f35..f00caa3 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -85,17 +85,16 @@ <!-- *********************************************************************** --> -<h2> - <a name="introduction">Introduction</a> -</h2> +<h2><a name="introduction">Introduction</a></h2> <!-- *********************************************************************** --> <div> <p>This document attempts to describe a few coding standards that are being used in the LLVM source tree. Although no coding standards should be regarded as -absolute requirements to be followed in all instances, coding standards can be -useful.</p> +absolute requirements to be followed in all instances, coding standards are +particularly important for large-scale code bases that follow a library-based +design (like LLVM).</p> <p>This document intentionally does not prescribe fixed standards for religious issues such as brace placement and space usage. For issues like this, follow @@ -103,14 +102,27 @@ the golden rule:</p> <blockquote> -<p><b><a name="goldenrule">If you are adding a significant body of source to a -project, feel free to use whatever style you are most comfortable with. If you -are extending, enhancing, or bug fixing already implemented code, use the style -that is already being used so that the source is uniform and easy to -follow.</a></b></p> +<p><b><a name="goldenrule">If you are extending, enhancing, or bug fixing +already implemented code, use the style that is already being used so that the +source is uniform and easy to follow.</a></b></p> </blockquote> - + +<p>Note that some code bases (e.g. libc++) have really good reasons to deviate +from the coding standards. In the case of libc++, this is because the naming +and other conventions are dictated by the C++ standard. If you think there is +a specific good reason to deviate from the standards here, please bring it up +on the LLVMdev mailing list.</p> + +<p>There are some conventions that are not uniformly followed in the code base +(e.g. the naming convention). This is because they are relatively new, and a +lot of code was written before they were put in place. Our long term goal is +for the entire codebase to follow the convention, but we explicitly <em>do +not</em> want patches that do large-scale reformating of existing code. OTOH, +it is reasonable to rename the methods of a class if you're about to change it +in some other way. Just do the reformating as a separate commit from the +functionality change. </p> + <p>The ultimate goal of these guidelines is the increase readability and maintainability of our common source base. If you have suggestions for topics to be included, please mail them to <a @@ -141,11 +153,11 @@ href="mailto:sabre@nondot.org">Chris</a>.</p> <div> <p>Comments are one critical part of readability and maintainability. Everyone -knows they should comment, so should you. When writing comments, write them as -English prose, which means they should use proper capitalization, punctuation, -etc. Although we all should probably -comment our code more than we do, there are a few very critical places that -documentation is very useful:</p> +knows they should comment their code, and so should you. When writing comments, +write them as English prose, which means they should use proper capitalization, +punctuation, etc. Aim to describe what a code is trying to do and why, not +"how" it does it at a micro level. Here are a few critical things to +document:</p> <h5>File Headers</h5> @@ -153,9 +165,7 @@ documentation is very useful:</p> <p>Every source file should have a header on it that describes the basic purpose of the file. If a file does not have a header, it should not be -checked into Subversion. Most source trees will probably have a standard -file header format. The standard format for the LLVM source tree looks like -this:</p> +checked into the tree. The standard header looks like this:</p> <div class="doc_code"> <pre> @@ -198,9 +208,8 @@ included, as well as any notes or "gotchas" in the code to watch out for.</p> <p>Classes are one fundamental part of a good object oriented design. As such, a class definition should have a comment block that explains what the class is -used for... if it's not obvious. If it's so completely obvious your grandma -could figure it out, it's probably safe to leave it out. Naming classes -something sane goes a long ways towards avoiding writing documentation.</p> +used for and how it works. Every non-trivial class is expected to have a +doxygen comment block.</p> <h5>Method information</h5> @@ -211,8 +220,7 @@ something sane goes a long ways towards avoiding writing documentation.</p> documented properly. A quick note about what it does and a description of the borderline behaviour is all that is necessary here (unless something particularly tricky or insidious 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> +figure out how to use your interfaces without reading the code itself.</p> <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> @@ -398,14 +406,6 @@ if ((V = getValue())) { <p>which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can be fixed by massaging the code appropriately.</p> -<p>These are the <tt>gcc</tt> warnings that I prefer to enable:</p> - -<div class="doc_code"> -<pre> --Wall -Winline -W -Wwrite-strings -Wno-unused -</pre> -</div> - </div> <!-- _______________________________________________________________________ --> |