python - 如何记录 Django 项目？

Question

我应该如何记录 Django 项目？我不是在谈论我正在创建的将推送到 github 的应用程序。它基本上是内部文档，可以帮助我们雇用的新开发人员跟上系统的速度。 (我想这就是一般文档的意义所在)

我是否应该按如下方式记录每个 View 函数、模型或表单:

def home(request):
    """View that renders the home page."""

class MyModel(models.Model):
    "Documentation regarding my model."""

这似乎有点矫枉过正。是否有一些好的项目可以让我寻找灵感？

Answer 1

根据我的经验，一种记录代码并将其开放给新开发人员理解的有效方法是文学编程。

https://en.wikipedia.org/wiki/Literate_programming

最主要的是有一个真正解释正在发生的事情的叙述，而不是一组松散的评论。

我更喜欢一种有点非标准的文学编程形式，我把我的评论放在代码后面，而不是代码之间。经验丰富的开发人员不会以这种方式受到阻碍。

就像:

class Node (object):                                    # Node representing atomary partial state in a state machine
    def __init__ (self, value = Nothing):               # Initial value is optional, not needed in case of dependent nodes ('Nothing' introduced y15m02d14)
        self.sinkNodes = []                             # Nodes that depend on this node
        self.links = []                                 # Zero or more links to bareRead / bareWrite pairs
        self.exceptions = []
        self.actions = []
        self.validator = lambda value: True             # Validators are deprecated, use exceptions instead

        self.persistent = False                         # Assume not worth persisting
        self.recursionCount = 0

        if value ==  Nothing:                           # If node is uninitialized
            self.event = 0                              #   It should be updated
        else:                                           # If node is supposed to be freely initialized
            self.currentValue = value                   #   Free initialisation
            self.previousValue = self.currentValue      #   Make sure previousValue is available in case of free initialisation
            self.event = currentEvent ()                #   Remember up to date

            if not value is None:                       #   If it is a freely initialized ordinary node rather than an event-only node
                self.persistent = True                  #       Remember it is part of a non-redundant basis for persistence


(etc.)

另一方面，盲目地在每个类和函数上添加明显的注释，然后使用工具生成文档对我理解任何东西都没有太大帮助。我需要手头有实际的代码，这里就是这种情况。

在你的代码中真正困难的地方，在整个宽度上都有一个解释 block 并没有什么坏处。

'''
As soon as we encounter a module in the chain that isn't already there, we'll have to create the remainder (tail) of the chain.

    e.g.
        import a.b.c.d.e
        import a.b.c

    will generate
        modules = {}
        __nest__ (a, 'b.c.d.e', __init__ (__world__.a.b.c.d.e))
        __nest__ (a, 'b.c', __init__ (__world__.a.b.c))

    The task of the __nest__ function is to start at the head object and then walk to the chain of objects behind it (tail),
    creating the ones that do not exist already, and insert the necessary module reference attributes into them.
'''

def __nest__ (headObject, tailNames, value):
    current = headObject

(etc.)