40、代码文档与科学出版的实用指南

代码文档与科学出版的实用指南

1. 代码文档基础

1.1 Readme 文件

Readme 文件通常与代码存放在一起，而非存档于大学图书馆、期刊文章或主开发者书架上的印刷装订本中。这样，在浏览源代码时更容易发现它。GitHub 会在包含 Readme 文件的目录首页展示该文件。不过，Readme 只是一个纯文本文件，只能传达代码库的最基本信息。提升 Readme 文件效果的方法包括使用标记格式、添加安装说明、提供最小示例以及引用额外信息。
安装说明示例：

./configure
make --prefix=/install/path
make install

1.2 代码注释

注释是代码中不运行或编译的行，仅用于帮助读者理解代码。在 Python 中，不同类型的注释有不同的表示方法：
- 单行注释用 # 开头。
- 多行注释和文档字符串通常用三引号或三撇号。

示例代码：

def the_function(var):
    """This is a docstring, where a function definition might live"""
    a = 1 + var  # this is a simple comment
    return a

但注释也可能带来问题，过多不必要的注释会使代码变得杂乱。例如：