让代码片段在半年后仍然有用

没有背景的代码片段会变成猜谜。今天你可能记得为何保存它，但半年后，缺失的输入、依赖或假设，可能比代码本身更重要。

把问题与解决方案一起保存

为笔记起描述性标题，解释片段做什么。记录语言、相关版本和依赖。加入最小的输入示例，以及测试时预期的输出。

如果片段来自某个来源，保留来源链接，检查复用条款。不要只因片段短就删除署名。保存的示例不要包含秘密、真实客户数据或特定环境凭据。

说明代码接受哪些输入、不接受哪些输入。注明是否修改文件、调用服务或需要权限。一条看似便利快捷方式的命令，在另一个目录中可能产生截然不同的效果。

Markdown 渲染器支持时，使用带语言标签的围栏代码块。MeatPad 项目编辑器可以把笔记放在相关源文件旁。语法高亮有助于阅读，却不能证明片段正确。

在计划使用的环境中，针对一个小而不重要的示例运行片段。将结果与保存的预期比较。笔记写下后，依赖和 API 都可能变化。

片段成为重复工作流程的一部分时，添加最近验证日期。如果它的背景已经扩展成完整程序，就把它升级为维护中的脚本，不要不断在笔记中累积修正。有用的片段是你能解释和测试的，而不只是能粘贴的。

从一条笔记开始。MeatPad 为笔记、Markdown 和项目文件提供 Mac 上的本地工作区，无须账户。