12、技术内容写作规范与风格指南

技术内容写作规范与风格指南

代码引用

在技术写作中，对于代码引用有着明确的规范。使用“code example”来指代包含在内容中用于说明开发任务的源代码。代码示例通常是代码片段，但也可能包含用户可以复制到计算机上进行编译和运行的完整示例。引入代码示例时，要用一个以句号结尾的完整句子，而非冒号。

使用“code sample”来指代用户可以下载到计算机并在开发项目中使用的源代码文件。例如，MSDN 上的示例库就提供了用户可以下载并在 Visual Studio 中使用的代码示例。需要注意的是，不要使用“code snippet”。

以下是一些编写代码的额外资源：
- Cwalina, Krzysztof 和 Brad Abrams. 《Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries》. 第 2 版. Addison - Wesley, 2008.
- Howard, Michael 和 David LeBlanc. 《Writing Secure Code》. 第 2 版. Redmond, WA: Microsoft Press, 2003.
- McConnell, Steve. 《Code Complete》. 第 2 版. Redmond, WA: Microsoft Press, 2004.
- MSDN 库中的“Design guidelines for developing class libraries”部分描述了开发 .NET Framework 类和组件的约定和建议。
- MSD