Ruff undocumented-public-class (D101)
undocumented-public-class проверяет отсутствие документации для публичных классов.
Почему это неправильно
Публичные классы должны быть документированы с помощью docstring, который описывает их назначение и поведение.
Обычно docstring класса должен:
- Описывать цель класса.
- Перечислять его публичные атрибуты и методы.
Если кодовая база придерживается стандарта оформления docstring для классов (например, NumPy или Google), следуйте ему для единообразия.
Пример ошибки
class Player:
def __init__(self, name: str, points: int = 0) -> None:
self.name: str = name
self.points: int = points
def add_points(self, points: int) -> None:
self.points += points
Как правильно
В формате NumPy:
class Player:
"""A player in the game.
Attributes
----------
name : str
The name of the player.
points : int
The number of points the player has.
Methods
-------
add_points(points: int) -> None
Add points to the player's score.
"""
def __init__(self, name: str, points: int = 0) -> None:
self.name: str = name
self.points: int = points
def add_points(self, points: int) -> None:
self.points += points
Или в формате Google:
class Player:
"""A player in the game.
Attributes:
name: The name of the player.
points: The number of points the player has.
"""
def __init__(self, name: str, points: int = 0) -> None:
self.name: str = name
self.points: int = points
def add_points(self, points: int) -> None:
self.points += points
