BOO入门 > 文件 (上一章:Boo专案的架构 下一章:有用的连结)


一份可沟通的东西,用来解释物件、系统或程序的某些特性。

我会把最重要的部份保留在最后:一份加上文件,说明自身代码的代码。

当文件化你的代码时,要确实记住:

  1. 你的文件应该要以英文书写。
  2. 使用完整的句子。
  3. 避免拼字/文法错误。
  4. 时态使用现在式。

文件书写时,以三个双引号包起来。

// 為函數加上摘要文件
def Hello():
"""Says "hello" to the world."""
    print "Hello, World!"

Hello()

至少,你应该要加上一段简单摘要的文件字串(docstring)。如果你的文件字串超过一行,那么三个双引号应该独立为一行。你或许注意到了,'Says "hello" to the world.' 不是一个完整的句子。摘要里的第一个句子,其实有"This member"的意思。(译注:所以实际上是 'This member says "hello" to the world.')

引数也可以加以文件化。

// 引數
def Hello(name as string):
"""
Say "hello" to the given name.
Param name: The name to say hello to.
"""
    print "Hello, ${name}!"

Hello()

试著自己读读看:'Say "hello" to this given name. Parameter name is defined as the name to say hello to.' (对给定的名字说 'hello'。引数 name 会作为要说 hello 的对象。') 这应该能影响你,让你继续使用完整的句子来文件化你的代码。

如果对引数的描述超过一行,你应该将描述移到新的一行,并且加上缩排。

// 長引數
def Hello(name as string):
"""
Say "hello" to the given name.
Param name:
    The name to say hello to.
    It might do other things as well.
"""
    print "Hello, ${name}!"

这同样适用于任何区块。这里有一份适用的标签(Tag)列表(译注:Param 就是其中的一个 tag):

Tag 描述
No tag 成员的摘要。
Param <name>: <description> 用来描述方法所使用的引数 <name>
Returns: <description> 描述方法的回传值。
Remarks: <text> 对成员提供更具描述性的文字。
Raises <exception>: <description> 描述为什么会提出例外。
Example: <short_description>: <code_block> 提供范例。
Include <filename>: <tagpath>[@<name>="<id>"] 表示需要引用其他档案。
Permission <permission>: <description> 描述所需要的许可(Permission)。
See Also: <reference> 指定你想出现在 See Also 节里的参考。

然后这儿是一份可以在 tag 内使用的 tag 列表:

Tag 描述
* <item><nowiki> | 無編號的列表 |- | <nowiki># <item> 有数字的列表
<<reference>> 对参考提供连结,例如:<int> 或 <string> 表示连结到整数与字串的说明。
[<param_reference>] 参考方法的某个参数。

这儿,是一份比较完整,加上文件的代码:

// 文件範例
import System

class MyClass:
"""Performs specific duties."""
    def constructor():
    """Initializes an instance of <MyClass>"""
        _rand = Random()
    
    def Commit():
    """Commits an action."""
        pass
    
    def CalculateDouble(i as int) as int:
    """
    Returns double the value of [i].
    Parameter i: An <int> to be doubled.
    Returns: Double the value of [i].
    """
        return i * 2
    
    def CauseError():
    """
    Causes an error.
    Remarks: This method has not been implemented.
    Raises NotImplementedException: This has not been implemented yet.
    """
        return NotImplementedException("CauseError() is not implemented")
    
    def DoSomething() as int:
    """
    Returns a number.
    Example: Here is a short example:
        print DoSomething()
    Returns: An <int>.
    See Also: MakeChaos()
    """
        return 0
    
    def MakeChaos():
    """
    Creates Chaos.
    Include file.xml: Foo/Bar[@id="entropy"]
    Permission Security.PermissionSet: Everyone can access this method.
    """
        print "I am making chaos: ${_rand.Next(100)}"
    
    def Execute():
    """
    Executes the protocol.
    Does one of two things,
    # Gets a sunbath.
    # Doesn't get a sunbath.
    """
        if _rand.Next(2) == 0:
            print "I sunbathe."
        else:
            print "I decide not to sunbathe."
    
    def Calculate():
    """
    Does these things, in no particular order,
    * Says "Hello"
    * Looks at you
    * Says "Goodbye"
    """
        thingsToDo = ["I look at you.", 'I say "Hello."', 'I say "Goodbye."']
        while thingsToDo.Length > 0:
            num = _rand.Next(thingsToDo.Length)
            print thingsToDo[num]
            thingsToDo.RemoveAt(num)
    
    [Property(Name)]
    _name as string
    """A name""" // documents the property, not the field
    
    Age as int:
    """An age"""
        get:
            return _rand.Next(8) + 18
    
    _age as int
    
    _rand as Random

这应该能让你比较知道如何去为你的代码加上文件。

我记得 Dick Brandon 说过一句很好的话:

 引述自: Dick Brandon
 文件就像性:如果它好的話,那當然很好﹔如果它爛的話,還是比什麼都沒有好。

译注:这里还是没提到,当一份代码有了文件说明自身以后,会在什么地方用到。加上文件说明,在编译以后,会产生一份 xml 档案,接著,你可以使用 NDoc 或是 Sandcastle 来产生出 Help 档案或其他格式的文件。