Members/tobaru/cbc/CbC_llvm: docs/CodingStandards.rst comparison

comparison docs/CodingStandards.rst @ 95:afa8332a0e37

LLVM 3.8

author	Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
date	Tue, 13 Oct 2015 17:48:58 +0900
parents	60c9769439b8
children	1172e4bd9c6f

comparison

equal deleted inserted replaced

-:f3e34b893a5f
+:afa8332a0e37
 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.
+it up on the LLVM-dev 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.  On the other
 hand, 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
+The ultimate goal of these guidelines is to increase the readability and
 maintainability of our common source base. If you have suggestions for topics to
 be included, please mail them to `Chris <mailto:sabre@nondot.org>`_.
 Languages, Libraries, and Standards
 ===================================
 * Explicit conversion operators: N2437_
 * Defaulted and deleted functions: N2346_
 * But not defaulted move constructors or move assignment operators, MSVC 2013
 cannot synthesize them.
+* Initializer lists: N2627_
+* Delegating constructors: N1986_
+* Default member initializers (non-static data member initializers): N2756_
+* Only use these for scalar members that would otherwise be left
+uninitialized. Non-scalar members generally have appropriate default
+constructors, and MSVC 2013 has problems when braced initializer lists are
+involved.
 .. _N2118: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2118.html
 .. _N2439: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm
 .. _N1720: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1720.html
 .. _N1984: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf
 .. _N3272: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm
 .. _N2429: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2429.htm
 .. _N2242: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2242.pdf
 .. _N2437: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2437.pdf
 .. _N2346: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm
-.. _MSVC-compatible RTTI: http://llvm.org/PR18951
+.. _N2627: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2672.htm
+.. _N1986: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1986.pdf
+.. _N2756: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2756.htm
 The supported features in the C++11 standard libraries are less well tracked,
 but also much greater. Most of the standard libraries implement most of C++11's
 library. The most likely lowest common denominator is Linux support. For
 libc++, the support is just poorly tested and undocumented but expected to be
 * Not all of the type traits are implemented
 * No regular expression library.
 * While most of the atomics library is well implemented, the fences are
 missing. Fortunately, they are rarely needed.
 * The locale support is incomplete.
-* ``std::initializer_list`` (and the constructors and functions that take it as
-an argument) are not always available, so you cannot (for example) initialize
-a ``std::vector`` with a braced initializer list.
-* ``std::equal()`` (and other algorithms) incorrectly assert in MSVC when given
-``nullptr`` as an iterator.
 Other than these areas you should assume the standard library is available and
 working as expected until some build bot tells you otherwise. If you're in an
 uncertain area of one of the above points, but you cannot test on a Linux
 system, your best approach is to minimize your use of these features, and watch
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
 ///
 /// \file
-/// \brief This file contains the declaration of the Instruction class, which is
+/// This file contains the declaration of the Instruction class, which is the
-/// the base class for all of the VM instructions.
+/// base class for all of the VM instructions.
 ///
 //===----------------------------------------------------------------------===//
 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
 The next section in the file is a concise note that defines the license that the
 file is released under.  This makes it perfectly clear what terms the source
 code can be distributed under and should not be modified in any way.
 The main body is a ``doxygen`` comment (identified by the ``///`` comment
-marker instead of the usual ``//``) describing the purpose of the file.  It
+marker instead of the usual ``//``) describing the purpose of the file.  The
-should have a ``\brief`` command that describes the file in one or two
+first sentence or a passage beginning with ``\brief`` is used as an abstract.
-sentences.  Any additional information should be separated by a blank line.  If
+Any additional information should be separated by a blank line.  If an
-an algorithm is being implemented or something tricky is going on, a reference
+algorithm is being implemented or something tricky is going on, a reference
 to the paper where it is published should be included, as well as any notes or
 *gotchas* in the code to watch out for.
 Class overviews
 """""""""""""""
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Use the ``\file`` command to turn the standard file header into a file-level
 comment.
-Include descriptive ``\brief`` paragraphs for all public interfaces (public
+Include descriptive paragraphs for all public interfaces (public classes,
-classes, member and non-member functions).  Explain API use and purpose in
+member and non-member functions).  Don't just restate the information that can
-``\brief`` paragraphs, don't just restate the information that can be inferred
+be inferred from the API name.  The first sentence or a paragraph beginning
-from the API name.  Put detailed discussion into separate paragraphs.
+with ``\brief`` is used as an abstract. Put detailed discussion into separate
+paragraphs.
 To refer to parameter names inside a paragraph, use the ``\p name`` command.
 Don't use the ``\arg name`` command since it starts a new paragraph that
 contains documentation for the parameter.
 A minimal documentation comment:
 .. code-block:: c++
-/// \brief Does foo and bar.
+/// Sets the xyzzy property to \p Baz.
-void fooBar(bool Baz);
+void setXyzzy(bool Baz);
 A documentation comment that uses all Doxygen features in a preferred way:
 .. code-block:: c++
 .. code-block:: c++
 // In Something.h:
-/// \brief An abstraction for some complicated thing.
+/// An abstraction for some complicated thing.
 class Something {
 public:
-/// \brief Does foo and bar.
+/// Does foo and bar.
 void fooBar();
 };
 // In Something.cpp:
 };
 // Bar isn't POD, but it does look like a struct.
 struct Bar {
 int Data;
-Foo() : Data(0) { }
+Bar() : Data(0) { }
 };
 Do not use Braced Initializer Lists to Call a Constructor
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 if you return from each case of a covered switch-over-enum because GCC assumes
 that the enum expression may take any representable value, not just those of
 individual enumerators. To suppress this warning, use ``llvm_unreachable`` after
 the switch.
-Use ``LLVM_DELETED_FUNCTION`` to mark uncallable methods
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Prior to C++11, a common pattern to make a class uncopyable was to declare an
-unimplemented copy constructor and copy assignment operator and make them
-private. This would give a compiler error for accessing a private method or a
-linker error because it wasn't implemented.
-With C++11, we can mark methods that won't be implemented with ``= delete``.
-This will trigger a much better error message and tell the compiler that the
-method will never be implemented. This enables other checks like
-``-Wunused-private-field`` to run correctly on classes that contain these
-methods.
-For compatibility with MSVC, ``LLVM_DELETED_FUNCTION`` should be used which
-will expand to ``= delete`` on compilers that support it. These methods should
-still be declared private. Example of the uncopyable pattern:
-.. code-block:: c++
-class DontCopy {
-private:
-DontCopy(const DontCopy&) LLVM_DELETED_FUNCTION;
-DontCopy &operator =(const DontCopy&) LLVM_DELETED_FUNCTION;
-public:
-...
-};
 Don't evaluate ``end()`` every time through a loop
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Because C++ doesn't have a standard "``foreach``" loop (though it can be
 emulated with macros and may be coming in C++'0x) we end up writing a lot of

Mercurial > hg > Members > tobaru > cbc > CbC_llvm

comparison docs/CodingStandards.rst @ 95:afa8332a0e37