使用文档字符串记录Python的@property“属性”

Question

我了解到，文档字符串（docstrings）更多的是个人喜好，而不是固定规则。不过，我想听听一些比我聪明的人对此的看法……

这样记录Python中@get和@set属性的方式算不算合理呢？

class Handle(rgm.RigModule):
    '''
    Handle nodes are intended to be keyable transforms, made viewable by shape nodes connected as children

    @Properties:

        parent:
            Transform: Returns Transform instance if parent exists, otherwise None
        parent.setter:
            (str): Sets parent transform. (Accepts string name of transform, or any instance of the Transform class)

        shape:
            str: returns string representation of current shape
        shape.setter:
            (str): sets current shape using string representation provided.  If string key does not exist in library, shape will be set to None

        shapeDraw:
            dict: returns dictionary of shape data
        shapeDraw.setter:
            (dict): sets current shapes using data

        shapeColor:
            int: returns integer representation of current shape color
        shapeColor.setter:
            (int): sets current shape color using integer provided.

        shapeColor:
            int: returns integer representation of current shape color
        shapeColor.setter:
            (int): sets current shape color using integer provided.

        shapeTranslate:
            list: returns a 3list of the shape nodes relative offset translation
        shapeTranslate.setter:
            (list): sets relative offset translation of the shape nodes

        shapeRotate:
            list: returns a 3list of the shape nodes relative offset rotation
        shapeRotate.setter:
            (list): sets relative offset rotation of the shape nodes

        shapeScale:
            list: returns a 3list of the shape nodes relative offset scale
        shapeScale.setter:
            (list): sets relative offset scale of the shape nodes

        shapeMatrix:
            list: returns a 8list of the shape nodes relative offset matrix
        shapeMatrix.setter:
            (list): sets relative offset matrix of the shape nodes

Answer 1

文档字符串的格式取决于你使用的开发环境（IDE）或自动生成文档的工具。我可以举一个例子，关于我常用的PyCharm IDE。

如果你在使用PyCharm，文档字符串是一个很强大的工具，可以帮助提升IDE的分析结果。你可以在这里了解如何为这个IDE编写“正确”的文档字符串。下面是一些例子：

class Character(object):
    pass


class Item(object):

    def __init__(self, owner=None):
        """
        :type owner: Character or None
        """
        self.__owner = owner

    @property
    def owner(self):
        """:rtype: Animal"""
        return self.__owner

    @owner.setter
    def owner(self, value):
        """:type value: Character"""
        self.__owner = value


class ArmorItem(Item):
    def __init__(self, defence, owner=None):
        """
        :type defence: int
        :type owner: Character or None
        """
        super(ArmorItem, self).__init__(owner)
        self.__defence = defence

    @property
    def defence(self):
        """:rtype: int"""
        return self.__defence


class Shield(ArmorItem):

    def block(self, damage):
        """
        :param int damage: The damage that can hero get
        :rtype: bool
        """
        if self.defence > damage:
            return True
        return False


class Helm(ArmorItem):

    def save(self, damage):
        """
        :param int damage: The damage that can hero get
        :rtype: bool
        """
        if self.defence > damage:
            return True
        return False


class Sword(Item):

    def __init__(self, damage, owner=None):
        """
        :type damage: int
        :type owner: Character or None
        """
        super(Sword, self).__init__(owner)
        self.__damage = damage


class Hero(Character):

    def __init__(self, name, weapon, armors):
        """
        :param str name: Hero name
        :param weapon weapon: Hero weapon
        :param list of ArmorItem armors: The armor item that have hero
        """
        super(Hero, self).__init__()

        self.__name = name
        self.__weapon = weapon

        self.__armors = armors
        for armor in self.__armors:
            armor.owner = self

    @property
    def name(self):
        """:rtype: str"""
        return self.__name

    @property
    def weapon(self):
        """:rtype: Sword"""
        return self.__weapon

    @property
    def armors(self):
        """:rtype: list of ArmorItem"""
        return self.__armors


def main():
    """
    Here method documentation can be placed.
    There is a test function to show analyzer facilities when a good docstring specified.

    Of course where I wrote "error" it mean that not Python exception will be thrown.
    In this place analyzer (e.g. PyCharm) show that it's something wrong.
    """
    weapon_bad1 = Sword(34.2)  # Error because damage is not int
    weapon_bad2 = Sword(20, weapon_bad1)  # Error because owner is not appropriate class

    weapon = Sword(10)  # Ok
    helm = Helm(20)  # Ok
    shield = Shield(30)  # Ok

    # Specify that all_items it not list but it list of Item (any)
    all_items = [weapon, helm, shield]
    """:type: list of Item"""

    hero_bad = Hero("bad", weapon, all_items)  # Again error here because all_items is not ArmorItem list
    hero_good = Hero("good", weapon, [helm, shield])

    # "Cast type" to notify analyzer that we get not ArmorItem but we get concrete ArmorItem
    some_armor = hero_good.armors[0]
    """:type: Helm"""

    some_armor.save(10)  # Ok, Helm class has save method
    some_armor.block(10)  # Error, Helm class has not block method


if __name__ == "__main__":
    main()

如果每个方法都指定了正确的文档字符串，你在IDE中可以看到的效果是这样的：

注意，PyCharm的分析器在指定了文档字符串时会非常有帮助（你可以在答案开头的链接中找到更详细的文档字符串格式列表）。