From edbfc3b8ec92a8b9ed39dec95fdc82d9b8b8c9f1 Mon Sep 17 00:00:00 2001
From: Bjarne Stroustrup <bjarne@stroustrup.com>
Date: Mon, 1 Jan 2018 14:26:00 -0500
Subject: [PATCH] Clarifying (I hope) text and example added

addressing #980 and #9777
---
 CppCoreGuidelines.md | 30 +++++++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 5 deletions(-)

diff --git a/CppCoreGuidelines.md b/CppCoreGuidelines.md
index eac8399..209dd50 100644
--- a/CppCoreGuidelines.md
+++ b/CppCoreGuidelines.md
@@ -20294,24 +20294,44 @@ When declaring a class use the following order
 
 Use the `public` before `protected` before `private` order.
 
-Private types and functions can be placed with private data.
+##### Example
 
-Avoid multiple blocks of declarations of one access (e.g., `public`) dispersed among blocks of declarations with different access (e.g. `private`).
+    class X {
+    public:
+        // interface
+    protected:
+        // unchecked function for use by derived class implementations
+    private:
+        // implementation details
+    };
 
 ##### Example
 
+Sometimes, the default order of members conflicts with a desire to separate the public interface from implementation details.
+In such cases, private types and functions can be placed with private data.
+
     class X {
     public:
         // interface
     protected:
         // unchecked function for use by derived class implementations
     private:
-        // implementation details
+        // implementation details (types, functions, and data)
     };
 
-##### Note
+##### Example, bad
+
+Avoid multiple blocks of declarations of one access (e.g., `public`) dispersed among blocks of declarations with different access (e.g. `private`).
+
+    class X {   // bad
+    public:
+        void f();
+    public:
+        int g();
+        // ...
+    };
 
-The use of macros to declare groups of members often violates any ordering rules.
+The use of macros to declare groups of members often leads to violation of any ordering rules.
 However, macros obscures what is being expressed anyway.
 
 ##### Enforcement