From 1fc08f5e9ef733ef1ce6f363fecedc2260e78974 Mon Sep 17 00:00:00 2001 From: dim Date: Sat, 14 Apr 2012 13:54:10 +0000 Subject: Vendor import of llvm trunk r154661: http://llvm.org/svn/llvm-project/llvm/trunk@r154661 --- docs/CodingStandards.html | 132 +++++++++++++++++++++++++++++----------------- 1 file changed, 83 insertions(+), 49 deletions(-) (limited to 'docs/CodingStandards.html') diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index 3ccbfc9..847ac4c 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -31,6 +31,7 @@ Errors
  • Write Portable Code
  • Do not use RTTI or Exceptions
    • +
  • Do not use Static Constructors
  • Use of class/struct Keywords
    • @@ -84,17 +85,16 @@ -

    - Introduction -

    +

    Introduction

    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.

    +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).

    This document intentionally does not prescribe fixed standards for religious issues such as brace placement and space usage. For issues like this, follow @@ -102,14 +102,27 @@ the golden rule:

    -

    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.

    +

    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.

    - + +

    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.

    + +

    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 do +not 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.

    +

    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 Chris.

    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:

    +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:

    File Headers
    @@ -152,9 +165,7 @@ documentation is very useful:

    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:

    +checked into the tree. The standard header looks like this:

    @@ -197,9 +208,8 @@ included, as well as any notes or "gotchas" in the code to watch out for.
    
 
 
    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.
    
+used for and how it works.  Every non-trivial class is expected to have a
+doxygen comment block.
    
 
 
 
    Method information
    
@@ -210,8 +220,7 @@ something sane goes a long ways towards avoiding writing documentation.
    
 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.
    
+figure out how to use your interfaces without reading the code itself.
    
 
 
    Good things to talk about here are what happens when something unexpected
 happens: does the method return null?  Abort?  Format your hard disk?
    
@@ -397,14 +406,6 @@ if ((V = getValue())) {
 
    which shuts gcc up.  Any gcc warning that annoys you can
 be fixed by massaging the code appropriately.
    
 
-
    These are the gcc warnings that I prefer to enable:
    
-
-
    
-
    --Wall -Winline -W -Wwrite-strings -Wno-unused
-
    
-
    
-
    @@ -449,6 +450,51 @@ than dynamic_cast<>.

    +Do not use Static Constructors +

    +
    + +

    Static constructors and destructors (e.g. global variables whose types have +a constructor or destructor) should not be added to the code base, and should be +removed wherever possible. Besides well known problems +where the order of initialization is undefined between globals in different +source files, the entire concept of static constructors is at odds with the +common use case of LLVM as a library linked into a larger application.

    + +

    Consider the use of LLVM as a JIT linked into another application (perhaps +for OpenGL, custom languages, +shaders in +movies, etc). Due to the design of static constructors, they must be +executed at startup time of the entire application, regardless of whether or +how LLVM is used in that larger application. There are two problems with +this:

    + +
      +
    1. The time to run the static constructors impacts startup time of + applications — a critical time for GUI apps, among others.
      2. + +
    2. The static constructors cause the app to pull many extra pages of memory + off the disk: both the code for the constructor in each .o file and + the small amount of data that gets touched. In addition, touched/dirty pages + put more pressure on the VM system on low-memory machines.
      3. +
    + +

    We would really like for there to be zero cost for linking in an additional +LLVM target or other library into an application, but static constructors +violate this goal.

    + +

    That said, LLVM unfortunately does contain static constructors. It would be +a great project for someone to purge all +static constructors from LLVM, and then enable the +-Wglobal-constructors warning flag (when building with Clang) to ensure +we do not regress in the future. +

    + +
    + + +

    Use of class and struct Keywords

    @@ -1151,22 +1197,10 @@ prefer it.

    The use of #include <iostream> in library files is -hereby forbidden. The primary reason for doing this is to -support clients using LLVM libraries as part of larger systems. In particular, -we statically link LLVM into some dynamic libraries. Even if LLVM isn't used, -the static constructors are run whenever an application starts up that uses the -dynamic library. There are two problems with this:

    - -
      -
    1. The time to run the static c'tors impacts startup time of applications - — a critical time for GUI apps.
      2. - -
    2. The static c'tors cause the app to pull many extra pages of memory off the - disk: both the code for the static c'tors in each .o file and the - small amount of data that gets touched. In addition, touched/dirty pages - put more pressure on the VM system on low-memory machines.
      3. -
    - +hereby forbidden, because many common implementations +transparently inject a static constructor into +every translation unit that includes it.

    +

    Note that using the other stream headers (<sstream> for example) is not problematic in this regard — just <iostream>. However, raw_ostream provides various @@ -1527,7 +1561,7 @@ something.

    Chris Lattner
    LLVM Compiler Infrastructure
    - Last modified: $Date: 2011-11-03 07:43:23 +0100 (Thu, 03 Nov 2011) $ + Last modified: $Date: 2012-03-27 13:25:16 +0200 (Tue, 27 Mar 2012) $ -- cgit v1.1