From 684cf814c765e5261d3c3ff3d07c2fb9ade23606 Mon Sep 17 00:00:00 2001 From: Chris Lattner Date: Wed, 17 Nov 2010 17:14:55 +0000 Subject: various cleanups and other improvements, patch by Zhanyong Wan! git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@119515 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CodingStandards.html | 95 +++++++++++++++++++++++------------------------ 1 file changed, 47 insertions(+), 48 deletions(-) (limited to 'docs') diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index 44a55a5..011ac98 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -34,7 +34,7 @@
  • Style Issues
      -
    1. The High Level Issues +
    2. The High-Level Issues
      1. A Public Header File is a Module
        2. @@ -48,7 +48,7 @@
      2. Turn Predicate Loops into Predicate Functions
      3. -
    3. The Low Level Issues +
    4. The Low-Level Issues
      1. Assert Liberally
      2. Do not use 'using namespace std'
        3. @@ -58,8 +58,8 @@ loop
      3. #include <iostream> is forbidden
        4. -
      4. Avoid std::endl
      5. Use raw_ostream +
      6. Avoid std::endl
    5. Microscopic Details @@ -167,8 +167,8 @@ this:

      A few things to note about this particular format: The "-*- C++ -*-" 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 this tag is not necessary in .cpp files. The name of the file is also +is a C++ file, not a C file (Emacs assumes .h files are C files by default). +Note that this tag is not necessary 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.

      @@ -244,7 +244,7 @@ file should be listed. We prefer these #includes to be listed in this order:

        -
      1. Main Module header
        2. +
      2. Main Module Header
      3. Local/Private Headers
      4. llvm/*
      5. llvm/Analysis/*
        6. @@ -259,13 +259,13 @@ order:

        ... and each category should be sorted by name.

        -

        The "Main Module Header" file applies to .cpp file -which implement an interface defined by a .h file. This #include +

        The "Main Module Header" file applies to .cpp files +which implement an interface defined by a .h file. This #include should always be included first regardless of where it lives on the file -system. By including a header file first in the .cpp files that implement the +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 +form of documentation in the .cpp file to indicate where the interfaces it implements are defined.

        @@ -323,7 +323,7 @@ makes for incredible diffs that are absolutely worthless.

        -

        Okay, your first year of programming you were told that indentation is +

        Okay, in your first year of programming you were told that indentation is important. If you didn't believe and internalize this then, now is the time. Just do it.

        @@ -434,7 +434,7 @@ declare the symbol. This can lead to problems at link time.

        - The High Level Issues + The High-Level Issues
        @@ -462,7 +462,7 @@ together.

        In general, a module should be implemented with one or more .cpp files. Each of these .cpp files should include the header that defines -their interface first. This ensure that all of the dependences of the module +their interface first. This ensures 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.

        @@ -581,7 +581,7 @@ Value *DoSomething(Instruction *I) {
        -

        This fixes these problems. A similar problem frequently happens in for +

        This fixes these problems. A similar problem frequently happens in for loops. A silly example is something like this:

        @@ -616,6 +616,7 @@ structure the loop like this:

        Value *LHS = BO->getOperand(0); Value *RHS = BO->getOperand(1); if (LHS == RHS) continue; + ... }
        @@ -778,7 +779,7 @@ locality.

        - The Low Level Issues + The Low-Level Issues
        @@ -790,7 +791,7 @@ locality.

        -

        Use the "assert" function to its fullest. Check all of your +

        Use the "assert" macro to its fullest. Check all of your preconditions and assumptions, you never know when a bug (not necessarily even yours) might be caught early by an assertion, which reduces debugging time dramatically. The "<cassert>" header file is probably already @@ -799,7 +800,7 @@ it.

        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 +helps the poor debugger make sense of why an assertion is being made and enforced, and hopefully what to do about it. Here is one complete example:

        @@ -900,7 +901,7 @@ namespace with an "std::" prefix, rather than rely on the namespace of any source file that #includes the header. This is clearly a bad thing.

        -

        In implementation files (e.g. .cpp files), the rule is more of a stylistic +

        In implementation files (e.g. .cpp files), the rule is more of a stylistic rule, but is still important. Basically, using explicit namespace prefixes makes the code clearer, because it is immediately obvious what facilities are being used and where they are coming from, and more portable, because @@ -913,9 +914,9 @@ such, we never use 'using namespace std;' in LLVM.

        The exception to the general rule (i.e. it's not an exception for the std namespace) is for implementation files. For example, all of the code in the LLVM project implements code that lives in the 'llvm' namespace. -As such, it is ok, and actually clearer, for the .cpp files to have a 'using +As such, it is ok, and actually clearer, for the .cpp files to have a 'using namespace llvm' directive at their top, after the #includes. The -general form of this rule is that any .cpp file that implements code in any +general form of this rule is that any .cpp file that implements code in any namespace may use that namespace (and its parents'), but should not use any others.

        @@ -1024,11 +1025,9 @@ library. There are two problems with this:

        Note that using the other stream headers (<sstream> for example) is not problematic in this regard (just <iostream>). -However, raw_ostream provides various APIs that are better performing for almost -every use than std::ostream style APIs, so you should just use it for new -code.

        - -

        New code should always +However, raw_ostream provides various APIs that are better performing for almost +every use than std::ostream style APIs. +Therefore new code should always use raw_ostream for writing, or the llvm::MemoryBuffer API for reading files.

        @@ -1037,6 +1036,26 @@ the llvm::MemoryBuffer API for reading files.

        + Use raw_ostream +
        + +
        + +

        LLVM includes a lightweight, simple, and efficient stream implementation +in llvm/Support/raw_ostream.h which provides all of the common features +of std::ostream. All new code should use raw_ostream instead +of ostream.

        + +

        Unlike std::ostream, raw_ostream is not a template and can +be forward declared as class raw_ostream. Public headers should +generally not include the raw_ostream header, but use forward +declarations and constant references to raw_ostream instances.

        + +
        + + + +
        Avoid std::endl
        @@ -1059,26 +1078,6 @@ it's better to use a literal '\n'.

        - -
        - Use raw_ostream -
        - -
        - -

        LLVM includes a lightweight, simple, and efficient stream implementation -in llvm/Support/raw_ostream.h which provides all of the common features -of std::ostream. All new code should use raw_ostream instead -of ostream.

        - -

        Unlike std::ostream, raw_ostream is not a template and can -be forward declared as class raw_ostream. Public headers should -generally not include the raw_ostream header, but use forward -declarations and constant references to raw_ostream instances.

        - -
        - -
        Microscopic Details @@ -1095,7 +1094,7 @@ reasoning on why we prefer them.

        -

        We prefer to put a space before a parentheses only in control flow +

        We prefer to put a space before an open parenthesis only in control flow statements, but not in normal function call expressions and function-like macros. For example, this is good:

        @@ -1174,7 +1173,7 @@ get in the habit of always using preincrement, and you won't have a problem.

        -In general, we strive to reduce indentation where ever possible. This is useful +In general, we strive to reduce indentation wherever possible. This is useful because we want code to fit into 80 columns without wrapping horribly, but also because it makes it easier to understand the code. Namespaces are a funny thing: they are often large, and we often desire to put @@ -1219,7 +1218,7 @@ namespace llvm {

        Since the body is small, indenting adds value because it makes it very clear where the namespace starts and ends, and it is easy to take the whole thing in in one "gulp" when reading the code. If the blob of code in the namespace is -larger (as it typically is in a header in the llvm or clang namespaces), do not +larger (as it typically is in a header in the llvm or clang namespaces), do not indent the code, and add a comment indicating what namespace is being closed. For example:

        -- cgit v1.1