如何记录Django项目？

Question

我该如何记录Django项目？我不是在谈论我正在创建的应用程序,我将推送到github.它基本上是内部文档,可以帮助我们采用的新开发人员加快系统速度.(我想这一般是文档的重点)

我应该记录下面的每个视图功能,模型或表单:

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

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

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

Answer 1

有经验的编程是记录代码并将其开放给新开发人员理解的有效方法。

https://zh.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.)

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

在您的代码中真正困难的地方，在整个宽度上使用解释块不会有什么坏处。

'''
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.)