Question

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

我是否应该记录下面的每个视图功能，模型或表单：

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

另一方面，盲目地在每个班级和功能上放置一个明显的评论，然后使用工具生成doc并没有帮助我理解任何事情。我需要掌握实际的代码，这就是这里的情况。

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

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

如何记录Django项目？

1 个答案: