《代码即文档》学习研究

在计算机程序设计中，自文档化（或自描述）的源代码和用户界面遵循命名惯例和结构化的程序设计惯例，可以在不需要事先掌握特定知识的情况下进入角色进行工作。

在网络开发中，自文档化是指网站通过公开文档公开其创建的整个过程，其公开文档是开发过程的一部分。

常见的自文档系统的目标包括：

• 让源代码更容易阅读和理解。

• 尽量减少维护或扩展遗留系统所需的工作量。

• 减少系统的用户和开发人员查阅二级文档来源（如代码注释或软件手册）的需要。

• 通过自成一体的知识表征促进自动化。

自文档化代码是使用人类可读的名称来编写的，一般由一个反映符号含义的人类语言短语组成，如article.numberOfWords或TryOpen。代码还必须有一个清晰简洁的结构，以便人类读者能够很容易理解所使用的算法。

自文档化系统的目标能否实现以及实现的情况如何，取决于如下的因素：

• 命名惯例的统一性。

• 一致性。

• 应用范围和系统要求。

下面是一个非常简单的自文档代码的例子，使用命名约定来代替明确的注释，使代码的逻辑对人类读者更加清楚:

size_t count_alphabetic_chars(const char *text)
{
    if (text == NULL)
        return 0;
 
    size_t  count = 0;
 
    while (*text != '\0')
    {
        if (is_alphabetic(*text))
            count++;
        text++;
    }
 
    return count;
}