51369b610e
When an include is not surrounded by empty lines, its content is inlined on the same line as the adjacent content. That can lead to broken tags and other display issues. This PR fixes all such includes and introduces a validation step that forbids introducing the same problem again.
77 lines
2.8 KiB
Plaintext
77 lines
2.8 KiB
Plaintext
== Why is this an issue?
|
||
|
||
"Class-Private" methods that are never executed inside their enclosing class are dead code: unnecessary, inoperative code that should be removed. Cleaning out dead code decreases the size of the maintained codebase, making it easier to understand the program and preventing bugs from being introduced.
|
||
|
||
|
||
Python has no real private methods. Every method is accessible. There are however two conventions indicating that a method is not meant to be "public":
|
||
|
||
* methods with a name starting with a single underscore (ex: ``++_mymethod++``) should be seen as non-public and might change without prior notice. They should not be used by third-party libraries or software. It is ok to use those methods inside the library defining them but it should be done with caution.
|
||
* "class-private" methods have a name which starts with at least two underscores and ends with at most one underscore. These methods' names will be automatically mangled to avoid collision with subclasses' methods. For example ``++__mymethod++`` will be renamed as ``++_classname__mymethod++``, where ``++classname++`` is the method's class name without its leading underscore(s). These methods shouldn't be used outside of their enclosing class.
|
||
|
||
This rule raises an issue when a class-private method (two leading underscores, max one underscore at the end) is never called inside the class. Class methods, static methods and instance methods will all raise an issue.
|
||
|
||
=== Noncompliant code example
|
||
|
||
[source,python]
|
||
----
|
||
class Noncompliant:
|
||
|
||
@classmethod
|
||
def __mangled_class_method(cls): # Noncompliant
|
||
print("__mangled_class_method")
|
||
|
||
@staticmethod
|
||
def __mangled_static_method(): # Noncompliant
|
||
print("__mangled_static_method")
|
||
|
||
def __mangled_instance_method(self): # Noncompliant
|
||
print("__mangled_instance_method")
|
||
----
|
||
|
||
=== Compliant solution
|
||
|
||
[source,python]
|
||
----
|
||
class Compliant:
|
||
|
||
def __init__(self):
|
||
Compliant.__mangled_class_method()
|
||
Compliant.__mangled_static_method()
|
||
self.__mangled_instance_method()
|
||
|
||
@classmethod
|
||
def __mangled_class_method(cls):
|
||
print("__mangled_class_method")
|
||
|
||
@staticmethod
|
||
def __mangled_static_method():
|
||
print("__mangled_static_method")
|
||
|
||
def __mangled_instance_method(self):
|
||
print("__mangled_instance_method")
|
||
----
|
||
|
||
== Resources
|
||
|
||
* https://docs.python.org/3.8/tutorial/classes.html#private-variables[Python documentation – Private Variables]
|
||
* https://www.python.org/dev/peps/pep-0008/#designing-for-inheritance[PEP8 – Designing for Inheritance]
|
||
|
||
ifdef::env-github,rspecator-view[]
|
||
|
||
'''
|
||
== Implementation Specification
|
||
(visible only on this page)
|
||
|
||
=== Message
|
||
|
||
Remove this unused class-private "XXXX" method
|
||
|
||
|
||
'''
|
||
== Comments And Links
|
||
(visible only on this page)
|
||
|
||
include::../comments-and-links.adoc[]
|
||
|
||
endif::env-github,rspecator-view[]
|