From: peter klausler Date: Mon, 5 Feb 2018 23:28:17 +0000 (-0800) Subject: [flang] Convert c++style.txt to c++style.md. X-Git-Tag: llvmorg-12-init~9537^2~2975 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=7f9cf6125b7fd91cbd5c8c852da33c61aec4bd7d;p=platform%2Fupstream%2Fllvm.git [flang] Convert c++style.txt to c++style.md. Original-commit: flang-compiler/f18@6b846b3c55ad2a044934406832ba55fae737dc8e --- diff --git a/flang/c++style.md b/flang/c++style.md new file mode 100755 index 0000000..9a044f9 --- /dev/null +++ b/flang/c++style.md @@ -0,0 +1,133 @@ +## In brief: +* Use *clang-format* to resolve all layout questions. +* Where LLVM's C++ style guide is clear on usage, follow it. +* Otherwise, where a clear precedent exists in the project, follow it. +* Otherwise, where a good public C++ style guide is relevant and clear, + follow it. [Google's](https://google.github.io/styleguide/cppguide.html) + is pretty good and comes with lots of justifications for its rules. +## In particular: +### Files +1. File names should use dashes, not underscores. C++ sources have the +extension ".cc", not ".C" or ".cpp" or ".cxx". Don't create needless +source directory hierarchies. +1. Header files should be idempotent: +> #ifndef FORTRAN_headername_H_ +> #define FORTRAN_headername_H_ +> // code +> #endif // FORTRAN_headername_H_ +1. <#include> every header defining an entity that your project header or source +file actually uses directly. (Exception: when starts, as it should, +with <#include "foo.h">, and includes in order to define the +interface to the module foo, you don't have to redundantly <#include "bar.h"> +in .) +1.Order the #include directives for foo.cc as: +> #include "foo.h" // this module's interface comes first +> #include "armadillo.h" // other modules in this project, alphabetically +> #include "zebra.h" +> #include // C++ standard headers, alphabetically +> #include +> #include // C headers, alphabetically +### Naming +1. C++ names that correspond to STL names should look like those STL names +(e.g., *clear()* and *size()* member functions in a class that implements +a container). +1. Non-public data members should be named with leading miniscule (lower-case) +letters, internal camelCase capitalization, and a trailing underscore, +e.g. "DoubleEntryBookkeepingSystem myLedger_;". POD structures with +only public data members shouldn't use trailing underscores, since they +don't have class functions in which data members need to be distinguishable. +1. Accessor member functions are named with the non-public data member's name, +less the trailing underscore. Mutator member functions are named "set_..." +and should return *this. Don't define accessors or mutators needlessly. +1. Other class functions should be named with leading capital letters, +CamelCase, and no underscores, and, like all functions, should be based +on imperative verbs, e.g. "HaltAndCatchFire()". +1. It is fine to use short names for local variables with limited scopes, +especially when you can declare them directly in the for()/while()/if() +condition. Otherwise, prefer complete English words to abbreviations +when creating names. +### Commentary +1. Use // for all comments except for short /*notes*/ within statements. +When // follows code on a line, precede it with two spaces. Comments +should matter. Assume that the reader knows current C++ at least as +well as you do and avoid distracting her by calling out usage of new +features in comments. +### Layout +Always run clang-format. Here's what you can expect to see it do: +1. Indent with two spaces. +1. Don't indent , , and +accessibility labels. +1. Never use more than 80 characters per source line. +1. Don't use tabs. +1. Don't indent the bodies of namespaces, even when nested. +1. Function result types go on the same line as the function and argument +names. + +Don't try to make columns of variable names or comments +align vertically -- they are maintenance problems. + +Always wrap the bodies of , , , , , &c. +with braces, even when the body is a single statement or empty. The +opening <{< goes on +the end of the line, not on the next line. Functions also put the opening +<{> after the formal arguments or new-style result type, not on the next +line. Use <{}> for empty inline constructors and destructors in classes. + +Don't waste space on the screen with needless blank lines or elaborate block +commentary (lines of dashes, boxes of asterisks, &c.). Write code so as to be +easily read and understood with a minimum of scrolling. +### C++ language +Use *C++17*, unless some compiler to which we must be portable lacks a feature +you are considering. +1. Never throw or catch exceptions. +1. Never use run-time type information or dynamic_cast<>. +1. Never declare static data that executes a constructor. +Use {braced initializers} in all circumstances where they work, including +default data member initialization. They inhibit implicit truncation. +Don't use "= expr" initialization just to effect implicit truncation; +prefer an explicit static_cast<>. +1. Avoid unsigned types apart from , which must be used with care. +When just obviously works, just use . When you need something +bigger than , use rather than or . +1. Use namespaces to avoid conflicts with client code. Use one top-level +project namespace. Don't introduce needless nested namespaces within a +project when names don't conflict or better solutions exist. Never use +, especially not . Access +STL entities with names like >, without a leading <::>. +1. Prefer static functions to functions in anonymous namespaces in source files. +1. Use judiciously. When the type of a local variable is known and +easy to type, be explicit rather than using . +1. Use move semantics and smart pointers to make dynamic memory ownership +clear. Consider reworking any code that uses or a (non-placement) +operator . +1. Use references for const arguments; prefer const references to values for +all but small types that are trivially copyable (e.g., ). Use non-const +pointers for output arguments. Put output arguments last (pace the standard +C library conventions for & al.). +1. Prefer > to >. +1. Prefer to plain wherever will work. +1. Use and generously. +1. When a statement's labels do not cover all possible case values +explicitly, it should contains either a <"default:;> at its end or a + label that obviously crashes. +#### Classes +1. Define only POD structures with . Use and in +non-static member functions, not foo_> and Bar(x)>. +1. Define accessor and mutator member functions (implicitly) inline in the +class, after constructors and assignments. Don't needlessly define +(implicit) inline member functions in classes unless they really solve a +performance problem. +1. Try to make class definitions in headers concise specifications of +interfaces, at least to the extent that C++ allows. +1. When copy constructors and copy assignment are not necessary, +and move constructors/assignment is present, don't declare them and they +will be implicitly deleted. When neither copy nor move constructors +or assignments should exist for a class, explicitly <= delete;> all of them. +1. Make single-argument constructors (other than copy and move constructors) + unless you really want to define an implicit conversion. +#### Overall design preferences +Don't use dynamic solutions to solve problems that can be solved at +build time; don't solve build time problems by writing programs that +produce source code when macros and templates suffice; don't write macros +when templates suffice. Templates are statically typed, checked by the +compiler, and visible to debuggers. diff --git a/flang/c++style.txt b/flang/c++style.txt deleted file mode 100755 index 6707a59..0000000 --- a/flang/c++style.txt +++ /dev/null @@ -1,137 +0,0 @@ -In brief: - - Where LLVM's C++ style guide is clear, follow it. - - Otherwise, where a clear precedent exists in the project, follow it. - - Otherwise, where a good public C++ style guide is relevant and clear, - follow it. (Google's is pretty good and comes with lots of justifications - for its rules.) - -Some particular points: - -File names should use dashes, not underscores. C++ sources have the -extension ".cc", not ".C" or ".cpp" or ".cxx". Don't create needless -source directory hierarchies. - -C++ names that correspond to STL names should look like those STL names -(e.g., clear() and size() member functions). - -Non-public data members should be named with leading miniscule (lower-case) -letters, internal camelCase capitalization, and a trailing underscore, -e.g. "DoubleEntryBookkeepingSystem myLedger_;". POD structures with -only public data members shouldn't use trailing underscores, since they -don't have class functions in which data members need to be distinguishable. -Define only POD structures with "struct". Use "foo_" and "Bar(x)" in -non-static member functions, not "this->foo_" and "this->Bar(x)". - -Accessor member functions are named with the non-public data member's name, -less the trailing underscore. Mutator member functions are named "set_..." -and should return *this. Don't define accessors or mutators needlessly. - -Other class functions should be named with leading capital letters, -CamelCase, and no underscores, and, like all functions, should be based -on imperative verbs, e.g. "HaltAndCatchFire()". - -Header files should be idempotent: - #ifndef FORTRAN_headername_H_ - #define FORTRAN_headername_H_ - // code - #endif // FORTRAN_headername_H_ - -Use // for all comments except for short /*notes*/ within statements. -When // follows code on a line, precede it with two spaces. Comments -should matter. Assume that the reader knows current C++ at least as -well as you do and avoid distracting her by calling out usage of new -features in comments. - -Use {braced initializers} in all circumstances where they work, including -default data member initialization. They inhibit implicit truncation. -Don't use "= expr" initialization just to effect implicit truncation; -prefer an explicit static_cast<>. - -Avoid unsigned types apart from size_t, which must be used with care. -When int just obviously works, just use int. When you need something bigger -than int, use std::int64_t. - -Never throw or catch exceptions. -Never use run-time type information or dynamic_cast<>. -Never declare static data that executes a constructor. - -Indent with two spaces, except for public:/protected:/private: in classes, -which are indented by one. Never use more than 80 characters per source line. -Don't use tabs. Don't try to make columns of variable names or comments -align vertically -- they are maintenance problems. Don't indent the bodies -of namespaces, even when nested. - -Define accessor and mutator member functions (implicitly) inline in the -class, after constructors and assignments. Don't needlessly define -(implicit) inline member functions in classes unless they really solve a -performance problem. Try to make class definitions in headers concise -specifications of interfaces, at least to the degree that C++ allows. - -#include header that a project header or source file actually uses directly. -(Exception: when foo.cc starts with #include "foo.h", and foo.h includes -bar.h in order to define the interface to foo, you don't have to redundantly -include bar.h in foo.cc.) Order the #include directives for foo.cc as - - #include "foo.h" // this module's interface comes first - #include "armadillo.h" // other modules in this project, alphabetically - #include "zebra.h" - #include // C++ standard headers, alphabetically - #include - #include // C headers, alphabetically - -Put templates into headers when they need to be there. -Prefer static functions to functions in anonymous namespaces in source files. - -Use namespaces to avoid conflicts with client code. Use one top-level project -namespace. Don't introduce needless nested namespaces within a project -when names don't conflict or better solutions exist. Never use -"using namespace ...;", especially not "using namespace std;". Access -STL entities with names like "std::unique_ptr<>", without a leading "::". - -Don't waste space on the screen with needless blank lines or elaborate block -commentary (lines of dashes, boxes of asterisks, &c.). Write code so as to be -easily read and understood with a minimum of scrolling. Function result types -go on the same line as the function and argument names, if they can all fit -in 80 columns. - -It is fine to use short names for local variables with limited scopes, -especially when you can declare them directly in the for()/while()/if() -condition. Otherwise, prefer complete English words to abbreviations -when creating names. - -Use "auto" judiciously. When the type of a local variable is known and -easy to type, be explicit rather than using auto. - -Use move semantics and smart pointers to make dynamic memory ownership -clear. Consider reworking any code that uses malloc() or a (non-placement) -operator new. When copy constructors and copy assignment are not necessary, -and move constructors/assignment is present, don't declare them and they -will be implicitly "= delete;". When neither copy nor move constructors -or assignments should exist for a class, explicitly "= delete;" all of them. - -Use references for const arguments; prefer const references to values for -all but small types that are trivially copyable (e.g., int). Use non-const -pointers for output arguments. Put output arguments last (pace the standard -C library conventions for memcpy() & al.). - -Prefer "template" to "template". - -Prefer "enum class" to plain "enum" wherever enum class will work. - -Use constexpr and const generously. - -Always wrap the bodies of if(), else, while(), for(), do, &c. with braces, -even when the body is a single statement or empty. The opening "{" goes on -the end of the line, not on the next line. Functions also put the opening -"{" after the formal arguments or new-style result type, not on the next -line. Use "{}" for empty inline constructors and destructors in classes. - -Don't use dynamic solutions to solve problems that can be solved at -build time; don't solve build time problems by writing programs that -produce source code when macros and templates suffice; don't write macros -when templates suffice. Templates are statically typed, checked by the -compiler, and visible to debuggers. - -When a switch() does not cover all case values explicitly, it should -contains either a "default:;" at its end or a "default:" label that -crashes.