From 11275aa086f4608571a3622c3702298f9c13fc65 Mon Sep 17 00:00:00 2001 From: johan lundberg Date: Fri, 25 Mar 2016 18:14:37 +0100 Subject: [PATCH] Add links to GSL, structure to README.md --- CppCoreGuidelines.md | 1 + README.md | 42 ++++++++++++++++++++++++++---------------- 2 files changed, 27 insertions(+), 16 deletions(-) diff --git a/CppCoreGuidelines.md b/CppCoreGuidelines.md index a71f422..e4385f9 100644 --- a/CppCoreGuidelines.md +++ b/CppCoreGuidelines.md @@ -14335,6 +14335,7 @@ Without these facilities, the guidelines would have to be far more restrictive o The Core Guidelines support library is defined in namespace `gsl` and the names may be aliases for standard library or other well-known library names. Using the (compile-time) indirection through the `gsl` namespace allows for experimentation and for local variants of the support facilities. +The GSL is header only, and can be found at [GSL: Guideline support library](https://github.com/Microsoft/GSL). The support library facilities are designed to be extremely lightweight (zero-overhead) so that they impose no overhead compared to using conventional alternatives. Where desirable, they can be "instrumented" with additional functionality (e.g., checks) for tasks such as debugging. diff --git a/README.md b/README.md index 220f967..db53a84 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,46 @@ -#[C++ Core Guidelines](http://isocpp.github.io/CppCoreGuidelines) +#[C++ Core Guidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) ->"Within C++ is a smaller, simpler, safer language struggling to get out." +>"Within C++ is a smaller, simpler, safer language struggling to get out." >-- Bjarne Stroustrup -The C++ Core Guidelines are a collaborative effort led by Bjarne Stroustrup, much like the C++ language itself. They are the result of many -person-years of discussion and design across a number of organizations. Their design encourages general applicability and broad adoption but -they can be freely copied and modified to meet your organization's needs. +The [C++ Core Guidelines](CppCoreGuidelines.md) are a collaborative effort led by Bjarne Stroustrup, much like the C++ language itself. They are the result of many +person-years of discussion and design across a number of organizations. Their design encourages general applicability and broad adoption but +they can be freely copied and modified to meet your organization's needs. -The aim of the guidelines is to help people to use modern C++ effectively. By "modern C++" we mean C++11 and C++14 (and soon C++17). In other +## Getting started + +The guidelines themselves are found at [CppCoreGuidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines). + +Many of the guidelines make use of the header only [GSL: Guideline support library](https://github.com/Microsoft/GSL) + +## Background and scope + +The aim of the guidelines is to help people to use modern C++ effectively. By "modern C++" we mean C++11 and C++14 (and soon C++17). In other words, what would you like your code to look like in 5 years' time, given that you can start now? In 10 years' time? -The guidelines are focused on relatively higher-level issues, such as interfaces, resource management, memory management, and concurrency. Such -rules affect application architecture and library design. Following the rules will lead to code that is statically type safe, has no resource +The guidelines are focused on relatively higher-level issues, such as interfaces, resource management, memory management, and concurrency. Such +rules affect application architecture and library design. Following the rules will lead to code that is statically type safe, has no resource leaks, and catches many more programming logic errors than is common in code today. And it will run fast - you can afford to do things right. -We are less concerned with low-level issues, such as naming conventions and indentation style. However, no topic that can help a programmer is +We are less concerned with low-level issues, such as naming conventions and indentation style. However, no topic that can help a programmer is out of bounds. -Our initial set of rules emphasize safety (of various forms) and simplicity. They may very well be too strict. We expect to have to introduce +Our initial set of rules emphasize safety (of various forms) and simplicity. They may very well be too strict. We expect to have to introduce more exceptions to better accommodate real-world needs. We also need more rules. -You will find some of the rules contrary to your expectations or even contrary to your experience. If we haven't suggested you change your -coding style in any way, we have failed! Please try to verify or disprove rules! In particular, we'd really like to have some of our rules +You will find some of the rules contrary to your expectations or even contrary to your experience. If we haven't suggested you change your +coding style in any way, we have failed! Please try to verify or disprove rules! In particular, we'd really like to have some of our rules backed up with measurements or better examples. -You will find some of the rules obvious or even trivial. Please remember that one purpose of a guideline is to help someone who is less +You will find some of the rules obvious or even trivial. Please remember that one purpose of a guideline is to help someone who is less experienced or coming from a different background or language to get up to speed. -The rules are designed to be supported by an analysis tool. Violations of rules will be flagged with references (or links) to the relevant rule. +The rules are designed to be supported by an analysis tool. Violations of rules will be flagged with references (or links) to the relevant rule. We do not expect you to memorize all the rules before trying to write code. The rules are meant for gradual introduction into a code base. We plan to build tools for that and hope others will too. -Comments and suggestions for improvements are most welcome. We plan to modify and extend this document as our understanding improves and the -language and the set of available libraries improve. +## Contributions and LICENSE + +Comments and suggestions for improvements are most welcome. We plan to modify and extend this document as our understanding improves and the +language and the set of available libraries improve. More details are found at [CONTRIBUTING](./CONTRIBUTING.md) and [LICENSE](./LICENSE) .