From: Chris Lattner Date: Fri, 16 Mar 2012 22:34:37 +0000 (+0000) Subject: clarify the coding standards a bit. X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=748c1ec713bb592d44827d08c40876cec3ecc644;p=oota-llvm.git clarify the coding standards a bit. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@152957 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index a5f6f35b670..f00caa33225 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -85,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 @@ -103,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
@@ -153,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:

@@ -198,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

@@ -211,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?

@@ -398,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
-

-

-