[doc] Add an example for 'duplicate-code'

7 files changed, 66 insertions, 2 deletions

diff --git a/doc/data/messages/d/duplicate-code/bad/apple.py b/doc/data/messages/d/duplicate-code/bad/apple.py
new file mode 100644
index 000000000..10de7e6d4
--- /dev/null
+++ b/doc/data/messages/d/duplicate-code/bad/apple.py
@@ -0,0 +1,14 @@
+class Apple:
+    def __init__(self):
+        self.remaining_bites = 3
+
+    def take_bite(self):
+        if self.remaining_bites > 0:
+            print("You take a bite of the apple.")
+            self.remaining_bites -= 1
+        else:
+            print("The apple is already eaten up!")
+
+    def eaten_by_animal(self, animal):
+        self.remaining_bites = 0
+        print("The apple has been eaten by an animal.")
diff --git a/doc/data/messages/d/duplicate-code/bad/orange.py b/doc/data/messages/d/duplicate-code/bad/orange.py
new file mode 100644
index 000000000..faafce747
--- /dev/null
+++ b/doc/data/messages/d/duplicate-code/bad/orange.py
@@ -0,0 +1,16 @@
+class Orange: # [duplicate-code]
+    def __init__(self):
+        self.remaining_bites = 3
+
+    def take_bite(self):
+        if self.remaining_bites > 0:
+            print("You take a bite of the apple.")
+            self.remaining_bites -= 1
+        else:
+            print("The orange is already eaten up!")
+
+    def eaten_by_animal(self, animal):
+        if animal == "cat":
+            raise ValueError("A cat would never do that !")
+        self.remaining_bites = 0
+        print("The orange has been eaten by an animal.")
diff --git a/doc/data/messages/d/duplicate-code/details.rst b/doc/data/messages/d/duplicate-code/details.rst
index ab8204529..07f5c72fa 100644
--- a/doc/data/messages/d/duplicate-code/details.rst
+++ b/doc/data/messages/d/duplicate-code/details.rst
@@ -1 +1,9 @@
-You can help us make the doc better `by contributing <https://github.com/PyCQA/pylint/issues/5953>`_ !
+If you need to make a change to the logic or functionality of the duplicated
+code, you will need to identify all the places that need to be changed, which
+can be time-consuming and error-prone. If there are multiple copies of the
+same code, then you will also need to test each copy to ensure that the
+functionality is correct. Duplicate code can be confusing for someone who is
+trying to understand the logic and flow of the code if they come across multiple
+identical or nearly identical blocks of code. The reader can then skim and
+think something is identical when it actually isn't. This is particularly true
+during review.
diff --git a/doc/data/messages/d/duplicate-code/good.py b/doc/data/messages/d/duplicate-code/good.py
deleted file mode 100644
index c40beb573..000000000
--- a/doc/data/messages/d/duplicate-code/good.py
+++ /dev/null
@@ -1 +0,0 @@
-# This is a placeholder for correct code for this message.
diff --git a/doc/data/messages/d/duplicate-code/good/apple.py b/doc/data/messages/d/duplicate-code/good/apple.py
new file mode 100644
index 000000000..692a16cd9
--- /dev/null
+++ b/doc/data/messages/d/duplicate-code/good/apple.py
@@ -0,0 +1,5 @@
+from fruit import Fruit
+
+
+class Apple(Fruit):
+    ...
diff --git a/doc/data/messages/d/duplicate-code/good/fruit.py b/doc/data/messages/d/duplicate-code/good/fruit.py
new file mode 100644
index 000000000..ecbd7ed95
--- /dev/null
+++ b/doc/data/messages/d/duplicate-code/good/fruit.py
@@ -0,0 +1,14 @@
+class Fruit:
+    def __init__(self):
+        self.remaining_bites = 3
+
+    def take_bite(self):
+        if self.remaining_bites > 0:
+            print(f"You take a bite of the {self.__class__.__name__.lower()}.")
+            self.remaining_bites -= 1
+        else:
+            print(f"The {self.__class__.__name__.lower()} is already eaten up!")
+
+    def eaten_by_animal(self, animal):
+        self.remaining_bites = 0
+        print(f"The {self.__class__.__name__.lower()} has been eaten by an animal.")
diff --git a/doc/data/messages/d/duplicate-code/good/orange.py b/doc/data/messages/d/duplicate-code/good/orange.py
new file mode 100644
index 000000000..7b5421a8b
--- /dev/null
+++ b/doc/data/messages/d/duplicate-code/good/orange.py
@@ -0,0 +1,8 @@
+from fruit import Fruit
+
+
+class Orange(Fruit):
+    def eaten_by_animal(self, animal):
+        if animal == "cat":
+            raise ValueError("A cat would never do that !")
+        super().eaten_by_animal(animal)