Add documentation for 'too-many-lines' (#8323)

Co-authored-by: Pierre Sassoulas <pierre.sassoulas@gmail.com>

7 files changed, 39 insertions, 2 deletions

diff --git a/doc/data/messages/t/too-many-lines/bad.py b/doc/data/messages/t/too-many-lines/bad.py
new file mode 100644
index 000000000..43c73335f
--- /dev/null
+++ b/doc/data/messages/t/too-many-lines/bad.py
@@ -0,0 +1,16 @@
+def is_palindrome(string):  # [too-many-lines]
+    left_pos = 0
+    right_pos = len(string) - 1
+    while right_pos >= left_pos:
+        if not string[left_pos] == string[right_pos]:
+            return False
+        left_pos += 1
+        right_pos -= 1
+    return True
+
+
+def main():
+    print(isPalindrome("aza"))
+    print(isPalindrome("racecar"))
+    print(isPalindrome("trigger"))
+    print(isPalindrome("ogre"))
diff --git a/doc/data/messages/t/too-many-lines/details.rst b/doc/data/messages/t/too-many-lines/details.rst
index ab8204529..e4394708b 100644
--- a/doc/data/messages/t/too-many-lines/details.rst
+++ b/doc/data/messages/t/too-many-lines/details.rst
@@ -1 +1,9 @@
-You can help us make the doc better `by contributing <https://github.com/PyCQA/pylint/issues/5953>`_ !
+When a module has too many lines it can make it difficult to read and understand. There might be
+performance issue while editing the file because the IDE must parse more code. You need more expertise
+to navigate the file properly (go to a particular line when debugging, or search for a specific code construct, instead of navigating by clicking and scrolling)
+
+This measure is a proxy for higher cyclomatic complexity that you might not be calculating if you're not using ``load-plugins=pylint.extensions.mccabe,``. Cyclomatic complexity is slower to compute, but also a more fine grained measure than raw SLOC. In particular, you can't make the code less readable by making a very complex one liner if you're using cyclomatic complexity.
+
+The example simplify the code, but it's not always possible. Most of the time bursting the file
+by creating a package with the same API is the only solution. Anticipating and creating the file
+from the get go will permit to have the same end result with a better version control history.
diff --git a/doc/data/messages/t/too-many-lines/good.py b/doc/data/messages/t/too-many-lines/good.py
deleted file mode 100644
index c40beb573..000000000
--- a/doc/data/messages/t/too-many-lines/good.py
+++ /dev/null
@@ -1 +0,0 @@
-# This is a placeholder for correct code for this message.
diff --git a/doc/data/messages/t/too-many-lines/good/__init__.py b/doc/data/messages/t/too-many-lines/good/__init__.py
new file mode 100644
index 000000000..315d2189c
--- /dev/null
+++ b/doc/data/messages/t/too-many-lines/good/__init__.py
@@ -0,0 +1,4 @@
+__all__ = ["is_palindrome", "main"]

+

+from is_palindrome import is_palindrome

+from main import main

diff --git a/doc/data/messages/t/too-many-lines/good/is_palindrome.py b/doc/data/messages/t/too-many-lines/good/is_palindrome.py
new file mode 100644
index 000000000..c2e431474
--- /dev/null
+++ b/doc/data/messages/t/too-many-lines/good/is_palindrome.py
@@ -0,0 +1,2 @@
+def is_palindrome(string):
+    return string == string[::-1]
diff --git a/doc/data/messages/t/too-many-lines/good/main.py b/doc/data/messages/t/too-many-lines/good/main.py
new file mode 100644
index 000000000..c1670f234
--- /dev/null
+++ b/doc/data/messages/t/too-many-lines/good/main.py
@@ -0,0 +1,6 @@
+from is_palindrome import is_palindrome
+
+
+def main():
+    for string in ["aza", "racecar", "trigger", "ogre"]:
+        print(is_palindrome(string))
diff --git a/doc/data/messages/t/too-many-lines/pylintrc b/doc/data/messages/t/too-many-lines/pylintrc
new file mode 100644
index 000000000..025a55a16
--- /dev/null
+++ b/doc/data/messages/t/too-many-lines/pylintrc
@@ -0,0 +1,2 @@
+[main]
+max-module-lines=15