1. 为什么我的自用代码demo总是“写完就忘”聊聊这堆零散代码的真实价值先说个现象。基本上每个开发者本地都有一个或者很多个名叫demo、test、untitled的文件夹里面躺着几十上百个写完就丢的代码片段。我自己也一样从早期的C语言小实验到后来的Python脚本、Go工具、前端组件零零散散积累了不知道多少。前阵子想找一个以前写过的数据转换逻辑翻了大半天才找到找到之后又发现代码能跑但看不懂当时为什么那么写。那一刻我突然意识到自用代码demo这个事看着不起眼其实藏着很大的效率问题——它不只是代码还是一个开发者的知识沉淀系统。这篇博文我想聊的就是围绕“自用代码demo”这件事我自己建立的一套管理办法。不是什么高深理论就是一个普通开发者在实际工作中踩了不少坑之后慢慢摸索出来的流程和规范。如果你也有一堆demo代码不知道该怎么整理或者你写demo的时候总是图快、随手丢、最后再也找不到那这篇文章应该能给你一些可以直接用的思路。先给个简单的分类。我把自己电脑上的“自用代码demo”分成了这么几类验证型demo为了验证某个想法能不能跑通、某个API返回什么结构、某个库的某个特性是否符合预期写完测试完就完成了它的使命。原型型demo为了给正式项目打个样把核心交互或者核心流程先实现出来看看效果。学习型demo跟着文档或者课程敲的例子目的是理解原理不是为了生产。复用型demo某些代码片段写完发现挺好用后面不断会用到慢慢变成了个人工具库的一部分。这几种demo的生死节奏完全不一样。验证型和原型型大概率写完就报废学习型和复用型则有长期价值。所以我在整理的时候会先把它们分类再决定怎么处理。这个逻辑听起来很简单但实际执行的时候最大的障碍往往是——写完demo之后脑子一热直接就扔进某个角落了分类的念头根本没来得及产生。我自己早期就是这个状态。每次写demo新建一个文件夹名字随意比如test123、newproject、testAgain写完之后再也不管。结果就是半年之后文件夹里的东西自己看着都陌生。我相信很多读者也有类似的经历所以这篇文章的核心目的就是把“如何管理自用demo”这件事系统化让零散的代码真正变成可以随时调取的资产。2. demo的腐烂曲线与“临时心态”为什么随手写的东西总是靠不住2.1 临时心态是demo的第一大杀手我在整理自用demo时发现一个普遍的规律代码腐烂的速度和写代码时的临时心态成正比。所谓临时心态就是觉得“这个代码反正就我一个人看看跑通就行了不用注释、不用考虑健壮性、不用管目录结构”。这种心态本身没有错写demo就是为了快速验证谁会在验证一个思路的时候去做完整的企业级架构设计呢但问题出在很多复用型demo根本是在临时心态下写出来的——写的时候以为是一次性的结果后面发现这个逻辑用得还挺频繁于是回头再翻这段代码才发现变量名全是a、b、tmp函数.py文件安安静静连个注释都没有。这种情况下这段demo代码的价值就大打折扣了。我自己就吃过这种亏。早先写数据清洗的时候有一段处理异常日期格式的代码当时就是临时心态写出来的一个函数搞定完全没有边界处理。后来这个逻辑需要在正式项目里复用我不得不在正式项目里重新写一遍而且当时没加断言的日期一些情况正式项目跑起来才发现问题。如果当时写demo的时候就稍微正规一点这个坑完全可以避免。2.2 代码腐烂的三个阶段我把自用demo的腐烂过程总结成了三个阶段每个阶段都有鲜明的特征阶段一刚写完时——代码能跑、逻辑清晰、脑子里记得所有设计决策。这个阶段demo是“活的”价值最高。阶段二写完之后一周到一个月——代码还能跑但开始忘记为什么这样写。如果demo里没有任何注释这个阶段就已经开始觉得陌生了。根据我自己的经验这是demo的“半衰期”黄金回忆窗口很快就关闭了。阶段三三个月以后——代码大概率能跑但一眼看不明白。如果这个demo还依赖了当时临时安装的某个包、某个具体版本那它很可能直接跑不起来了。这三个阶段不是危言耸听几乎所有没有整理过的自用demo都会按这个节奏走向腐烂。所以我在做demo管理的时候核心目标就是在阶段一和阶段二之间做一次有效的归档动作把“活的记忆”转化为“可读的代码必要的说明”这样即使过了很久也能快速恢复上下文。2.3 数量失控带来的检索灾难除了代码本身的腐烂数量失控是另一个大问题。我粗略统计过自己的demo目录最多的时候有超过300个子文件夹很多文件夹里只有一两个文件。这个数量下即使给每个文件夹起了看起来还算合理的名字检索的时候依然头疼。举个例子。我之前的demo文件夹里有test_csv.py、csv_test2.py、read_csv_v3.py这样一堆名字如果不是逐个打开看根本分不清他们之间的差异。更可怕的是有些demo是同一个问题反复试了不同方案比如csv_read_1.py、csv_read_2.py、csv_read_2_final.py、csv_read_2_final_最终.py这种命名方式在数量少的时候还能忍数量一多系统就直接崩溃了。所以我要做的第一件事就是给demo制定一个统一的命名和目录规约。这个规约不复杂但需要长期坚持。具体怎么设计下一节详细说。3. 自用demo的目录规约一套可以长期执行的命名与存放策略3.1 先从宏观目录开始把demo从正式项目里剥离开我在整理的时候做的第一件事就是明确划分了一个独立的沙箱目录专门放自用demo。这个目录不参与正式项目的版本控制不跟公司的工作代码混在一起单纯就是自己的实验场。把这个目录独立出来的好处很多正式项目的代码库不会被大量实验性代码污染。demo目录可以建立不同的备份和清理机制甚至可以直接丢进网盘或云端私有仓库。心理上也会更放松“这里是沙箱怎么折腾都行”不会因为怕弄坏正式环境而束手束脚。我自己的目录结构大概是这样的~/sandbox/ ├── _archive/ # 已归档的demo不再活跃使用 ├── _template/ # 常用的模板工程比如Python项目模板、前端组件模板 ├── 2025-01/ # 按月份存放的临时实验代码 ├── 2025-02/ └── README.md # 整个沙箱目录的索引说明注意这里有个特殊设计就是把已归档的demo单独放了_archive文件夹。为什么会有这个设计呢因为我发现很多demo在写完之后并没有立即删除的价值某些时候可能还会翻出来参考一下但它们也不是每天都活跃要用的。如果把所有demo都堆在同一个目录里时间长了活跃的和不活跃的混在一起检索成本会不断上升。单独切一个_archive出来至少从物理层面就做了冷热分离。然后每个月新建一个文件夹比如2025-01、2025-02专门放这个月的验证型demo。这个按月分目录的做法主要是为了配合时间维度的检索——如果一个demo确实重要后面我会把它移动到更正式的位置如果一个月后这个demo还留在月度文件夹里那我就会直接清理掉它因为这说明它根本没有长期利用的价值。3.2 给每个demo一个“身份证”命名规约怎么定单独一个目录结构还不够更关键的是每个demo文件夹/文件的命名。我经过反复调整最后用一个固定的命名格式格式是[类别前缀]-[项目代号]-[说明文字]其中类别前缀我用几个固定的缩写前缀含义例子exp-验证型实验exp-readcsv-编码检测对比proto-原型型demoproto-login-无密码登录交互learn-学习型demolearn-docker-多阶段构建实验lib-复用型片段lib-json-带注释格式保留的序列化tool-工具型脚本tool-filebatch-重命名移动脚本项目代号是短斜线分隔的一个词表示这个demo的主题说明文字用简短的自然语言补充让人一眼就知道这个demo是干什么的。这套命名规约看起来很简单但真正执行起来会遇到一个老问题写demo的时候谁会去查表找前缀啊所以我的建议是不用一开始就在每个demo上做到完美命名但至少在项目收尾或归档的时候花30秒做一次重命名。之所以用exp-、proto-这种前缀还有一个实际好处在文件管理器里按名称排序同类demo会自动聚在一起。比如你所有learn-开头的文件夹会聚拢在一起找起来非常顺。这一点对于GUI浏览和终端里的ls操作都很方便。3.3 归档决策哪个该留哪个该删在按目录规约整理demo时有一个必须完成的问题这个demo到底要不要归档我给自己定了一个“三次筛选法”简单说就是看这个demo是否满足下面三个条件的任意一条还会不会再用这个demo里有没有自己以后可能还会查的代码逻辑、写法、坑位记录还值不值得参考有没有一些特殊的调试思路、边界情况总结或者某种库的使用方式还能不能扩展当前demo是不是某个未来功能的最小可行验证它有没有可能演变成一个小工具、一个组件如果一个demo既不满足上面三条中的任何一条也没有特殊的情感价值那我的建议是直接删除。删除这件事我在早期做的时候也会犹豫后来发现真删了就删了那些验证型demo本身的价值窗口就是一周过了窗口留着也是占地方。如果担心误删先放到_archive里过一个月再删也来得及。4. 从零散demo到可复用资产三层筛选法让代码长期发挥价值4.1 不是所有demo都该被“正规化”上一节提到的三次筛选法解决的是“删还是留”的问题。而一旦决定留下来就要解决“留下来之后怎么处理”的问题。这里我有个很重要的体会不是所有留下来的demo都要升级成正式工程。有些demo的“价值”就体现在“一行代码”或者“一个函数”上你把它做成完整工程反而浪费精力。比如我有一个lib-shell-管道处理带空格文件名的demo核心就是一小段shell脚本处理文件名含有空格的特殊转义。这种情况把它升级成全家桶工程明显不合逻辑它的价值在于片段本身可以被快速检索到。所以我将这种类型的demo专门整理成了“可复用片段库”而不是一个完整的项目工程。4.2 三层筛选法具体怎么做我在实际操作中会把留下来的demo分成了三个层级层级一原始demo保留原样——这类demo我直接保留在对应的月度文件夹里不动它的代码、不重构、不补注释。它们只是作为原始实验记录存在方便追溯某个想法的原始形态。为什么要保留原始形态因为有些实验记录比如你尝试过某种方案但没走通这样的“失败记录”也很有价值能提醒未来的自己这条路不要重复走。层级二沉淀片段提取可复用单元——当一个demo里有某个函数、类配置方案、或者一段命令被明确识别为“以后会用”我会把它从demo里提取出来整理成一个独立的“片段文件”。这个片段文件的格式统一包含核心代码、使用场景、依赖说明和注意事项。举个直观的例子我有一段处理中文文本分词后清洗的Python代码在多个项目里都用到过后来我就专门建了一个lib-py-文本清洗常用函数的片段文件夹里面用一个.py文件把所有相关的清洗函数整理好每个函数都写了docstring和示例调用。层级三工程化模块升级为可安装的工具/组件——如果某个沉淀片段在多个项目里持续使用并且发现需要反复维护那它就值得升级为工程化模块。比如我的日志工具、日期处理工具都是这样从demo一路升上来的。升级成工程化模块后就不再放在sandbox目录了而是挪到专门的个人工具库工程里甚至可以打包成pip包或者npm包。这一步的触发条件我很明确如果我在三个不同的项目里需要做同一件事那这件事就应该被封装成公共模块。这三层筛法有了之后自用demo从一个“写完就忘的临时文件”变成了可以被持续沉淀的知识资产。每一次实验不管成功还是失败经过筛选后都会沉淀成某种有索引的资产。这个变化看起来不大但时间久了会产生巨大的复利效应——你每一次的思考、踩坑和验证都被存下来了而不是写完就丢。4.3 从demo到工程化模块的实际案例我拿自己一个具体的demo来演示这个过程。假设我写了一个从数据库中读取数据并生成PDF报告的demo一开始只是验证捷克的报告库能不能满足需求写完就丢在exp-文件夹里。后来过了两个月我在另一个任务里需要做类似的事情突然想起这个demo就翻了出来。这时候因为demo里没有注释我花了接近一小时才想起来当时是怎么配置表格样式的。这就是一个明确的“沉淀信号”——我觉得这段代码未来还会用于是把它提取成lib-py-pdf表格生成基础套件把所有常用的表格样式函数整理好写上docstring和示例。再过了一段时间我在第三个项目里又用到了这套东西并且还做了一些增强于是它就直接被移到一个独立的Git仓库正式成了一个公共工具库。这个案例看着平淡但很典型。demo升级成工程化模块关键不在于代码多复杂而在于你是不是识别出了它的复用价值。识别这个价值往往需要你在多个项目之间来回走动的时候留意那些反复出现的共性需求。5. 沙箱实验环境的构建如何不污染正式开发环境自用demo在写的时候不可避免会折腾各种依赖临时安装新的Python包、Node模块、甚至会在系统里注册某些服务。如果不加管控这些折腾迟早会污染正式的开发环境。我自己早期就吃过这种亏为了测试一个库直接用pip install装到了全局环境里结果某个正式项目因为它升级了依赖版本跑出了完全不一样的结果排查了半天才发现是全局环境的锅。5.1 语言级别虚拟环境是底线首先从语言层面Python的venv、Node的npm局部安装其实是最低要求。我现在给自己定了一条硬性规定不管多小的demo必须运行在独立的环境里。Python的话我给每个demo文件夹建一个.venv目录激活后该装什么装什么不需要了直接删掉整个demo子目录环境也跟着没了互不牵连。这条规则在一开始会觉得麻烦毕竟有时候demo只有一百多行代码建虚拟环境都好几秒。但坚持下来之后会发现它避免的坑远大于那几秒钟。而且现在工具已经很成熟了Python可以用uv来快速创建虚拟环境Node项目更不用说自带npm和yarn局部依赖管理根本不费事。5.2 容器级别一次性环境实验如果demo涉及的不是简单依赖而是需要特定版本的数据库、消息队列或者某些外部服务虚拟环境就不够用了。这时候用Docker会方便得多。注意我这里是说“配合demo使用的单次环境”不是要求给每个demo做个完整的容器化工程。我的做法是在沙箱目录里维护一个通用的docker-compose.yml模板里面预定义了一些常用的服务容器PostgreSQL、MySQL、Redis、RabbitMQ每个服务都有独立的端口映射和数据卷。要验证某个demo就启动其中对应的服务用完直接关掉数据卷也可以随时清空。这样正式开发环境不会多出一堆常驻服务系统资源也干净。5.3 系统级别全局环境只留最基础的东西“尽量把demo级依赖控制在沙箱内”这个原则延伸到系统层面后自然就得到一个结论系统的全局语言环境里尽量只装最基础、最稳定的工具。我的全局Python环境里甚至连requests都没有全局装全部依赖都放虚拟环境里。这样做的代价是一开始建环境时要多跑一条pip install好处是永远不会出现全局环境依赖混乱的场面。5.4 沙箱目录要不要纳入版本控制这个问题的答案因人而异我自己用的方案是沙箱目录整体纳入一个私有Git仓库但只推送到自己的私有远端仓库绝不跟工作代码放一起。这样做有几个明确的收益任何demo改动都能追溯哪怕过了很久也能找到当时的时间点。如果某天忘了某个demo的代码为什么改过git log能给出不少线索。demo的代码不存在“写出来只能留在本地这唯一一份”的风险换了电脑也不会丢。当然前提是你要保证沙箱里不放敏感信息。我给自己加了一条纪律demo用到的连接串、密钥、token一律通过环境变量或本地配置文件传入绝对不允许写死在demo代码里。一旦发现某个demo需要访问真实生产环境的敏感数据我会直接放弃这个demo另用模拟数据代替。6. demo的档案化改造让未来的自己还能快速看懂6.1 一个README解决上下文重建问题每个真正需要留存的demo我都会给它配一个最小化的README。注意是“最小化”不是那种几十行的工程文档。我定的最低标准是四个信息点这个demo解决的问题是什么它用的主要技术栈和关键依赖是什么怎么运行它一条命令能搞定最佳当时踩过的坑或者需要注意的地方。这四个点写完大概率也就十行以内。很多读者可能会觉得既然就十行那当时写demo的时候顺便记一笔不好吗这个问题我在实际操作里得到的答案是不好因为写demo的时候正处于“心流状态”最不想做的就是停下来写文档。所以我的策略是demo刚写完可以完全不管文档但凡是决定要留下来的demo在归档动作发生的时候必须顺手补一个README。补完README之后这个demo的“可读性”就有了质的提升。以后不管是grep关键词还是浏览文件夹都能快速定位到自己想要的东西。6.2 代码注释的尺度demo注释和项目注释完全不同正式项目的注释我一般强调“为什么”demo的注释我则会多加一点“它是什么”。原因很简单demo代码常常不完整、没有上下文未来翻看的时候光有“为什么”不足以理解这些代码片段当时的用途。举个例子我有一段处理CSV文件BOM头的代码如果是正式项目注释写“去除UTF-8 BOM以避免首列出现\ufeff字符”就够了。但在demo里我会额外加上一段“这个场景出现在用Excel编辑过CSV之后重新读入Python时Excel默认在文件头加BOM。如果你的CSV来历比较正规可能不需要这段。”这种在正式项目里显得啰嗦的注释在demo里却非常有用因为它提供了上下文背景和判断依据。6.3 标签系统与检索文件系统加全文搜索的组合光有目录和README在demo数量超过100个之后还是会不够用。我的方案是引入标签思维但不用专门的笔记软件就用文件系统加全文检索工具。所谓“标签思维”核心是这样的同一个demo可能涉及多个关键主题比如“数据清洗”“编码处理”“Pandas性能优化”但在目录结构上你很难让这个demo同时出现在多个位置。所以我会在README里加一个“标签”字段把相关的关键词都列出来。比如## 标签 数据清洗, 编码检测, 中文文本, 正则表达式, Pandas然后当需要检索的时候直接在整个沙箱目录里做全文搜索。这个方案不需要任何复杂工具你的IDE全局搜索、ripgrep或者系统自带搜索都能轻松找到这些关键词。我还会在沙箱根目录的README.md里维护一个“高频检索清单”就是把那些经常用到的主题和对应demo位置列出来。这个清单不需要经常更新但每次花个一两分钟维护一下对整个沙箱的可用性提升非常明显。6.4 模板工程的存在意义关于_template目录这里也提一下。我发现自用demo很多时候是在重复“搭架子”——比如又开始一个新的Python小项目又要配置一遍项目结构、依赖管理、代码风格检查。如果每次都从零开始那同一个框架会被我重复造无数遍。后来我在沙箱里维护了一个_template目录里面放了几个常用模板工程Python库模板、Python脚本模板、Node命令行工具模板、最小前端组件模板等。每个模板都预配置了虚拟环境文件、目录结构、README骨架和License说明。有了模板之后起一个新demo的时间从原来的十几分钟缩短到几分钟时间主要省在环境配置和初始结构调整上。这个模板文件本身其实也是从无数个自用demo里提炼出来的“元demo”。7. 自用demo的工具链选型我踩过哪些坑、最后留下了什么7.1 关于笔记软件与专门知识库工具的是否取舍我周围有不少开发者习惯把demo代码放进Notion、印象笔记这类知识管理工具里。我自己也尝试过一段时间但最终放弃了。原因很直接代码放进笔记软件脱离了实际运行环境一旦想跑起来验证还得复制回本地来回折腾成本很高。也有一些专门做代码片段管理的软件比如很多编辑器都内置了代码片段功能。但这种工具的适用对象是“短片段”比如一段正则、一段HTTP请求一旦涉及多个文件、目录结构和依赖配置就很难管理了。所以我最后的结论是自用demo的核心载体还是文件系统。文件系统最灵活、不锁定、能直接运行配合一些轻量检索工具效率不比专业软件差。笔记软件可以记一些经验、教训、草稿型思考但最终的代码实体一定放在文件系统里两者不混用。7.2 轻量检索工具的选择与配置我在终端里最常用的检索工具是ripgreprg命令。配合沙箱目录的.rgignore文件可以把_archive、.venv、node_modules这些目录排除掉这样搜索时又快又准。我还配了一个简单的alias命令直接搜沙箱alias sboxrg --hidden -g !.venv -g !node_modules -g !_archive -g !*.pyc用的时候直接sbox 关键词 ~/sandbox就能全局搜索。如果你用的是Windows也可以用类似的工具或者直接用VS Code的全局搜索功能效果也差不多。7.3 从命名规范到自动化的进阶一个小脚本解决批量归档当成型的目录规约和文件名规约开始稳定之后下一个自然的需求就是把重复动作自动化。比如每个月月初我会跑一个小脚本自动创建这个月的实验目录顺便把上个月还在活跃目录里但超过30天未修改的demo移到_archive同时打印一份“归档清单”供我确认。这个小脚本本身也是我自己“自用代码demo”的产物。一开始它只是一个挂在tool-前缀下的手工脚本后来因为用起来顺手逐渐增加了参数、交互、帮助文档最后也放进了一个独立的个人工具库里。这恰好印证了前面说的“三层筛选法”——一个实用的demo经过时间的验证自然而然就会升级成工程化模块。8. 定期清理的节奏与心态不要靠一时冲动要靠机制8.1 为什么定期清理如此重要整理自用demo这事最难的不是技术而是坚持节奏。我自己经历过几次大规模清理每次都是一股脑把几百个demo删掉或归档看起来很爽但没过多久又会有新的demo堆出来。后来意识到靠“一次性的整理”根本没戏“定期清理的机制”才是正解。我把清理节奏分成了三档每日顺手档每次写完demo抽10秒想一下这个代码还用得上吗用不上就直接删不心疼。每月归档档每月一次把当月文件按命名规约重新整理一遍删除无用demo有复用价值的沉淀到片段层。每季度复盘档每三个月整体看一遍沙箱目录找出那些已经被复用超过三次的片段考虑是否升级为工程化模块。这里最难执行的是“每日顺手档”因为它需要改变习惯。为了让自己更容易坚持我把“删除无价值demo”这件事变成了一件很有仪式感的事每次删完一堆垃圾demo顺手在沙箱根目录的README.md里记一笔“本月清理删除N个实验文件归档M个片段”。这种小小的成就感真的能维持很长时间的执行力。8.2 清理时的心态调整别把demo当成“没有安全感”的囤积物很多开发者不清理demo本质上是“怕丢了什么”。要改变这个心态我的体会是把沙箱目录当成“堆肥箱”而不是“仓库”。堆肥箱的逻辑是你往里面扔各种有机废料它们慢慢分解成肥料然后用于花圃。仓库的逻辑是你往里面放东西希望它们永远留在那里谁都不准动。一旦把自己的角色从“仓库管理员”调成“堆肥者”就会让“删除”和“归档”变得自然起来。那些验证型demo它们在分解过程中已经给了你足够多的信息哪些方案走不通哪些API是什么行为完成使命后删掉完全不可惜。真正有价值的部分早就通过片段沉淀和工程化升级被“消化”掉了根本不存在“丢”的遗憾。8.3 备份策略要跟上沙箱里保留下来的正式资产沉淀片段、模板工程、工具模块我会有专门的备份机制一是推送到私有Git仓库的远端二是定期做一次打包备份扔到云端三是最重要的核心工具库我还会额外做一个异地备份。而对于那些验证型demo和已归档到_archive的老实验我的策略就比较简单粗暴——只保留本地不特意备份。因为它们的价值窗口已经过去了就算真的硬盘坏了丢了损失其实很有限。这个“分级备份”的思路能帮你把备份成本控制在合理的范围内。9. 从自用demo到写作输出的一个意外收获最后分享一个我自己没预料到的收获。在系统的整理自用demo一段时间后我发现这些demo慢慢变成了一个“素材库”不只是代码素材更是写作和技术分享的素材库。当你把一段demo从“只能跑”进化到“沉淀片段”再到“工程化模块”时你会发现你对这个问题的理解深入了很多。那个时候你讲出来或写出来的东西就不再是“今天我用了某个库”而是“我如何通过三次实践最终把这段代码沉淀成了一个稳定方案”。这种从实战中生长出来的内容往往才是最有价值的。我自己很多篇技术笔记其实都是从自用demo里翻出来的。我不用刻意找素材只要定期整理沙箱就有源源不断的主题冒出来。那条数据清洗的边界情况、那次因为全局依赖版本冲突导致的调试经历、那个反复重写过三次的日期解析函数都成了很好的分享素材。所以如果你还在头疼“想写技术内容但不知道写什么”我建议你先去翻翻自己的demo文件夹——里面大概率躺着十几个值得写下来的故事。回到开头说的那句话自用代码demo不只是零散代码它是一个开发者的知识沉淀系统。花点时间把这个系统搭好让它可维护、可检索、可沉淀短期看是增加了不少管理成本长期看每一分投入都值回来。希望这篇文章里的思路和细节能给你一些可以落地的参考。