示例工程【免费下载链接】algorithmsA collection of algorithms and data structures项目地址https://gitcode.com/gh_mirrors/algorithms39/algorithms点击查看免费下载导读本文以当前仓库中的技能规范文档.gemini/SKILL.md为骨架系统讲解一个面向学习者的算法与数据结构仓库Java Bazel应遵循的编码约定从每个文件都要能教学的方法级文档、覆盖边缘用例的测试体系到保持代码整洁的重构策略与统一的格式化标准。读完本文你将掌握一套可直接落地到任意算法项目含 LeetCode 风格题目、图论、动态规划代码的规范化流程并能对照仓库中 Bellman-Ford、编辑距离、Union-Find 等真实实现理解这些规范如何在实际源码与测试中生根。一、技能文档的背景与定位.gemini/SKILL.md采用 YAML frontmatter 声明技能元数据技能名为algorithms-education描述中明确其适用场景——任何基于 Java 的教学型编码项目并列出触发关键词algorithms、data structures、graph theory、sorting、searching、trees、DP、BFS、DFS、linked lists、heaps、segment trees、union-find 等以及clean up / simplify / document / refactor / add tests这类维护类请求。这说明该规范的核心定位是让仓库中的每一个算法实现不仅能跑而且能教——对没有深厚 CS 背景的学习者同样友好。全文共定义 8 项技能代码文档、测试覆盖、重构与代码债、格式化与一致性、简化、Bug 检测、算法讲解注释、main 方法位置。以下逐一展开并结合仓库源码给出落地证据。二、Skill 1代码文档——每个文件不仅要实现更要教学目标GoalEvery file should teach, not just implement.每个文件都应传授知识而不仅仅是实现功能。2.1 方法级文档Method-Level Documentation每个 public 方法都应带有一段 doc comment依次说明五件事做什么——用一句通俗英语描述方法功能怎么做——简述采用的方法/算法思路参数——每个输入代表什么返回值——输出含义时间/空间复杂度——必须包含 Big-O。文档给出的标准模板如下以 Bellman-Ford 为例/** * Finds the shortest path from a source node to all other nodes * using Bellman-Fords algorithm. Unlike Dijkstras, this handles * negative edge weights and detects negative cycles. * * param graph - adjacency list where graph[i] lists edges from node i * param start - the source node index * param n - total number of nodes in the graph * return dist array where dist[i] shortest distance from start to i, * or Double.NEGATIVE_INFINITY if node i is in a negative cycle * * Time: O(V * E) — relaxes all edges V-1 times * Space: O(V) — stores distance array */这一模板在仓库中得到了完整落实。例如 BellmanFordAdjacencyList.java 的bellmanFord方法逐条注明了param graph邻接表、param V顶点数、param start起始节点并说明负环节点会被标记为Double.NEGATIVE_INFINITY。再看 UnionFind.java 的find方法不仅描述功能还点明使用路径压缩扁平化树结构这一实现机理unify方法则注明了按 size 合并以保持树平衡。2.2 关键行内注释注释为什么而非是什么文档强调注释应聚焦逻辑不明显的位置解释为什么the why而不是复述代码在做什么。示例以负权环检测的两个阶段为例// Relax all edges V-1 times. After V-1 passes, shortest paths // are guaranteed if no negative cycles exist. for (int i 0; i n - 1; i) { for (Edge e : edges) { if (dist[e.from] e.cost dist[e.to]) { dist[e.to] dist[e.from] e.cost; } } } // If we can still relax an edge after V-1 passes, that node // is reachable from a negative cycle — mark it as -infinity. for (int i 0; i n - 1; i) { for (Edge e : edges) { if (dist[e.from] e.cost dist[e.to]) { dist[e.to] Double.NEGATIVE_INFINITY; } } }真实源码中的写法与此完全一致——BellmanFordAdjacencyList.java 先用注释说明第一轮松弛保证最短路径成立的先决条件无负环再解释第二轮遍历的意义若还能松弛则该节点从负环可达标记为-Infinity。这类注释是注释 why的典范。2.3 文件级头注释File-Level Header每个文件顶部应以注释块说明文件内的算法结构包括算法名、功能概述、典型使用场景、运行命令可选的参考链接标注。文档模板/** * Bellman-Ford Shortest Path Algorithm * * Computes single-source shortest paths in a weighted graph. * Handles negative edge weights and detects negative cycles. * * Use cases: * - Graphs with negative weights (where Dijkstra fails) * - Detecting negative cycles (e.g., currency arbitrage) * * Run with: * bazel run //src/main/java/com/williamfiset/algorithms/graphtheory:BellmanFordAdjacencyList * * see a hrefhttps://en.wikipedia.org/wiki/Bellman-Ford_algorithmWikipedia/a */仓库中 Kahns.java 的文件头堪称范例先讲 Kahn 算法迭代移除无入边节点的原理再给出验证来源Kattis builddeps 题目、运行命令bazel run //src/main/java/com/williamfiset/algorithms/graphtheory:Kahns以及时间复杂度O(VE)。EditDistanceIterative.java 的头注释则补充了三种操作的可配置成本insertion/deletion/substitution、DP 表dp[i][j]的语义以及See also: EditDistanceRecursive的交叉引用——这正是保留教学价值的体现。运行前提文件头中的bazel run命令依赖仓库根目录的 BUILD.bazel 与 MODULE.bazelBazel 模块配置。每个包目录下的 BUILD 文件用java_binary声明了main_class与runtime_deps例如 graphtheory/BUILD 为 BellmanFordAdjacencyList 定义了同名目标dp/BUILD 则为每个 DP 解法列出了对应的bazel run目标。因此文档中的运行命令可直接照抄执行。三、Skill 2测试覆盖——用测试证明正确性并教学边缘用例目标Every algorithm has tests that prove it works and teach edge cases.3.1 测试文件结构测试应与源文件并列放置或放入tests/目录命名镜像源文件BellmanFord.java→BellmanFordTest.java。当前仓库将测试统一放在src/test/java/com/williamfiset/algorithms/...下与源码同包例如源码 BellmanFordAdjacencyList.java 对应测试 BellmanFordAdjacencyListTest.java源码 EditDistanceIterative.java 对应测试 EditDistanceIterativeTest.java。3.2 每个算法都应覆盖的测试类别基础/常规路径Happy path——典型输入、期望输出边缘用例——空输入、单元素、重复元素边界条件——最大值/最小值、0、Integer.MAX_VALUE已知的刁钻输入——常导致朴素实现出错的场景性能 sanity check可选——大输入不卡死、不崩溃。仓库测试对以上类别覆盖得相当细致。BellmanFordAdjacencyListTest.java 中singleNode()单节点、twoNodesDirectEdge()常规路径、disconnectedGraph()不连通图、reachableNegativeCycleMarkedNegativeInfinity()可达负环、unreachableNegativeCycleDoesNotTaintReachableNode()不可达负环不得污染可达节点这是非常刁钻的陷阱用例、exampleFromMain()复现main()中的图与期望输出。EditDistanceIterativeTest.java 则覆盖了null输入抛异常、双空串、空→非空纯插入、非空→空纯删除、插入替换混合以及一个典型陷阱当替换成本过高时插入删除反而更便宜testInsertDeleteCheaperThanSubstitute。3.3 测试命名约定测试方法名应像一句话一样可读Test public void testShortestPathSimpleGraph() { ... } Test public void testDetectsNegativeCycle() { ... } Test public void testSingleNodeGraph() { ... } Test public void testDisconnectedNodes() { ... }仓库在此基础上更进一步方法名直接省略test前缀、以行为描述命名如unreachableNodeDoesNotPolluteCostOfReachableNeighbor、nodeReachableOnlyThroughUnreachableIntermediaryStaysUnreachable——一个失败的测试几乎无需看断言就能知道哪里错了。3.4 测试文档每个测试都要解释测什么、为什么重要每个测试方法应带简短注释说明覆盖的场景及其重要性。仓库中这种注释甚至画出了图结构/** * Graph with a negative cycle reachable from the source. * Bellman-Ford should mark affected nodes as NEGATIVE_INFINITY. * * 0 --5-- 1 --(-10)-- 2 --3-- 1 * (creates cycle 1→2→1 with net cost -7) */ Test public void testDetectsNegativeCycle() { // ... test body }BellmanFordAdjacencyListTest.java 中的注释同样用 ASCII 图 文字推导解释为何dist[1] (-100) Inf不应更新dist[2]——这是把测试当作教材的绝佳示范。3.5 修改代码时必须同步更新测试每当代码发生变更必须运行既有测试检查回归新行为引入时补充新测试方法签名或行为变化时更新既有测试仅当某特性被有意移除时才删除对应测试。这一测试与代码同生命周期的约定正是仓库中大量同名*Test.java与源码保持同步存在的根因。四、Skill 3重构与代码债——在整洁与教学价值之间取舍目标Keep the codebase clean without losing educational value.4.1 什么代码应当删除与另一实现完全相同、且无新增教学价值的重复实现死代码不可达代码、未使用的辅助方法没有说明存在原因的被注释代码块临时的调试/打印语句。4.2 什么时候应该保留看似重复的代码保留传授不同思路的替代实现。文档给出的判断示例// ✓ KEEP — BFS and DFS solutions to the same problem teach different techniques public int[] bfsSolve(int[][] grid) { ... } public int[] dfsSolve(int[][] grid) { ... } // ✓ KEEP — iterative vs recursive shows tradeoffs public int fibRecursive(int n) { ... } public int fibIterative(int n) { ... } // ✗ REMOVE — identical logic, just different variable names public int search_v1(int[] arr, int target) { ... } public int search_v2(int[] arr, int target) { ... }保留替代实现时需用注释明确其教学目的/** * Recursive implementation of binary search. * Compare with binarySearchIterative() to see the iterative approach. * The iterative version avoids stack overhead for large arrays. */这一约定在当前仓库中有着系统性的落地动态规划目录同时存在 EditDistanceIterative.java自底向上与 EditDistanceRecursive.java自顶向下记忆化前者头部明确写着 See also: EditDistanceRecursive for a top-down memoized approach后缀数组目录则有SuffixArraySlow、SuffixArrayMed、SuffixArrayFast三个不同复杂度实现——它们不是冗余而是教学梯度。4.3 代码债检查清单重构时逐项扫描未使用的 import未使用的变量或参数可合并或简化过的方法应命名为具名常量的魔法数字同一文件内不一致的命名应抽取为辅助函数的复制粘贴代码块五、Skill 4格式化与一致性——全仓库统一风格目标Uniform style across the entire repository.5.1 命名约定短而清晰采用短、清晰的变量名用简洁换取可读性// ✓ GOOD — short and clear int n graph.length; int[] dist new int[n]; boolean[] vis new boolean[n]; Listint[] adj new ArrayList(); QueueInteger q new LinkedList(); int src 0; int dst n - 1; // ✗ BAD — verbose names that clutter algorithm logic int numberOfNodesInGraph graph.length; int[] shortestDistanceFromSource new int[numberOfNodesInGraph]; boolean[] hasNodeBeenVisited new boolean[numberOfNodesInGraph]; Listint[] adjacencyListRepresentation new ArrayList(); QueueInteger breadthFirstSearchQueue new LinkedList(); int sourceNodeIndex 0; int destinationNodeIndex numberOfNodesInGraph - 1;仓库通用短名速查表跨仓库保持一致名称含义n元素/节点数量m边数量i, j循环下标from, to图的节点端点cost边权重dist距离数组vis访问标记数组adj邻接表q队列pq优先队列st栈dp动态规划表ans结果/答案lo低指针/下界hi高指针/上界mid中点src源节点dst目标节点cnt计数器sz大小cur当前元素prev前一个元素next后一个元素若与关键字冲突则用nxt这一约定在源码中随处可见BellmanFordAdjacencyList用V顶点数、start起点、dist距离数组UnionFind用sz分量大小数组、parent父节点数组、numComponents分量数Kahns用inDegree、q、order。变量名一眼即可读懂其角色。5.2 格式化规则花括号左花括号与语句同行if (...) {缩进2 个空格不用 Tab空行方法之间留一个空行短方法内部不加空行最大行长100 字符软限制import按包分组组内按字母序禁止通配符导入。5.3 Big-O 记法约定复杂度表达式必须显式写出乘法与括号避免歧义// ✓ GOOD — explicit and unambiguous // Time: O(n*log(n)) // Time: O(n*log^2(n)) // Time: O(n^2*log(n)) // ✗ BAD — missing multiplication and parentheses // Time: O(n log n) // Time: O(n log^2 n) // Time: O(n^2 log n) // Simple expressions without multiplication are fine as-is // Time: O(n) // Time: O(n^2) // Time: O(log(n)) // Space: O(n)仓库源码遵循该写法Kahns.java 写为O(VE)EditDistanceIterative.java 写为O(n*m)且同时标注时间与空间UnionFind.java 则用O(α(n))注明摊还含义。5.4 for 循环体必须独占一行即使只有一条语句循环体也要换行书写嵌套循环更应如此// ✗ BAD — body on same line as for for (int j 0; j n; j) augmented[i][j] matrix[i][j]; // ✓ GOOD — body on its own line for (int j 0; j n; j) augmented[i][j] matrix[i][j]; // ✓ GOOD — nested for loops, each level on its own line for (int i 0; i n; i) for (int j 0; j n; j) for (int k 0; k n; k) result[i][j] m1[i][k] * m2[k][j];对照 BellmanFordAdjacencyList.java 的松弛循环三层嵌套for每层独占一行与规范完全一致。5.5 避免 Java StreamsStreams 会削弱初学者对逻辑的直读性应改用普通循环// ✗ AVOID — streams obscure the logic for beginners int sum Arrays.stream(arr).filter(x - x 0).reduce(0, Integer::sum); // ✓ PREFER — a loop is immediately readable int sum 0; for (int x : arr) { if (x 0) sum x; }这一点与教学优先的整体定位一脉相承普通循环的每一步都是显式可见的。六、Skill 5简化——最简单的正确代码是最好的教材目标The simplest correct code teaches the best.6.1 简化策略减少嵌套——反转条件、提前返回early return// ✗ AVOID — deep nesting if (node ! null) { if (node.left ! null) { if (node.left.val target) { return true; } } } return false; // ✓ PREFER — early returns keep code flat if (node null) return false; if (node.left null) return false; return node.left.val target;抽取重复逻辑——但仅在确实降低复杂度时在有助于讲清概念时使用标准库——Arrays.sort()、Collections.swap()、Math.min()等是学习者必须知道的存在可以放心使用如 EditDistanceIterative.java 用Math.min取三种操作的最小值移除不必要的包装——不要用一层方法包住另一个方法的单次调用能省则省的数据结构——当大小已知时int[]比ArrayListInteger更清晰如dist、dp数组的大量使用。6.2 什么不该简化不要把两个明显独立的算法阶段合并进一个循环只为省几行Bellman-Ford 的松弛与负环检测就是两个独立阶段源码 明确分两个for块实现不要用三元运算符替换清晰的 if/else 链而牺牲可读性不要删除那些给复杂表达式命名的中间变量。七、Skill 6Bug 检测——接触代码时主动排查目标Catch bugs proactively whenever touching code.7.1 Bug 扫描检查清单修改任何代码行时主动检查并报告差一错误——循环边界、数组下标、栅栏柱fence-post问题整数溢出——乘法或加法可能超出 int 范围空/空集合检查——对 null 数组、空集合缺少防护未初始化值——变量赋值前被使用尤其是 dp 数组比较方向错误——vs、vs死循环——永不成立的条件、缺失的递增数组越界——无范围检查地使用i1、i-1图相关——缺少 visited 检查有环时死循环、有向图方向搞反错误的 base case——dp[0]、递归基线、空图可变性 bug——修改了调用方期望保持不变的输入拷贝 vs 引用——需要深拷贝时用了浅拷贝返回值误用——忽略返回值、返回了错误变量7.2 如何报告 Bug发现 Bug 后要清晰报告文档给出了标准格式含文件、行号、问题描述与修复建议 BUG FOUND in BellmanFord.java line 42: Loop runs i n but should be i n - 1. The extra iteration incorrectly marks reachable nodes as being in a negative cycle. FIX: Change i n to i n - 1有趣的是这个i n 应为 i n - 1的典型差一错误正是本仓库测试重点防护的场景——BellmanFordAdjacencyListTest.java 中unreachableNodeDoesNotPolluteCostOfReachableNeighbor等用例正是为了防止松弛轮数错误导致可达节点被误标-Infinity。八、Skill 7 与 Skill 8算法讲解注释与 main 方法位置8.1 Skill 7算法讲解注释目标很直接帮助学习者理解每个算法背后的为什么。这与 Skill 1 的文件级头注释 关键行注释形成呼应——讲解注释不是复述代码而是解释算法成立的原理、复杂度推导与适用边界。仓库中这类注释的密集程度很高例如BellmanFordAdjacencyList对为何第二轮遍历能识别负环的说明EditDistanceIterative.java 对dp[i][j]三个来源对角替换/匹配、上方删除、左侧插入的讲解都属于解释 why的注释。8.2 Skill 8main 方法放在文件底部Java 文件的main方法应放在文件靠近底部的位置以保持全项目一致。这符合先讲算法、再给可运行示例的阅读顺序学习者先读完类的字段与方法教学主体最后才看到main中的运行示例。仓库实现广泛遵循这一点——BellmanFordAdjacencyList.java 的main位于文件末尾并在注释中给出了 9 节点样例图的完整输出含-Infinity与Infinity的预期结果EditDistanceIterative.java 同样把main置于末尾且每个println都带注释说明期望值如// 0、// 30、// 24让读者无需运行即可验证。九、规范落地全景从技能文档到仓库实践的映射把 8 项技能与仓库证据汇总可以清晰看到这份规范并非纸上谈兵技能核心要求仓库落地证据1 代码文档方法级五要素注释、注释 why、文件级头BellmanFordAdjacencyList.java、Kahns.java、UnionFind.java2 测试覆盖五类用例、句读式命名、测试带文档BellmanFordAdjacencyListTest.java、EditDistanceIterativeTest.java3 重构删死代码、保留教学性替代实现、债务清单Iterative/Recursive 双实现、Slow/Med/Fast 后缀数组4 格式化短名速查表、2 空格、Big-O 显式乘号、避免 Streams各源码中dist/vis/sz/dp的普遍使用与O(n*m)写法5 简化提前返回、标准库善用、不合并独立阶段Bellman-Ford 两个独立松弛阶段、Math.min三操作取小6 Bug 检测12 项扫描清单、结构化报告测试中对差一错误、不可达负环污染等陷阱的专门用例7 算法讲解注释解释 whyDP 表推导、负环检测原理注释8 main 位置置于文件底部BellmanFordAdjacencyList.java、EditDistanceIterative.java十、如何验证与使用这套规范在当前仓库中验证规范效果主要依赖两套工具链1. 运行算法示例借助仓库根目录的 BUILD.bazel 与各包目录下的 BUILD 文件如 graphtheory/BUILD、dp/BUILD直接执行文件头注释中给出的命令例如bazel run //src/main/java/com/williamfiset/algorithms/graphtheory:BellmanFordAdjacencyList bazel run //src/main/java/com/williamfiset/algorithms/dp:EditDistanceIterative2. 运行测试各src/test/java包下与源码同名镜像的测试类如 BellmanFordAdjacencyListTest.java、EditDistanceIterativeTest.java可先运行既有用例确认无回归再对照 Skill 2 的五类用例清单补充新场景每次改代码后都应回到这一步遵守修改代码必更新测试的约定。需要说明的适用前提仓库为只读镜像本文只介绍查看、运行与配置方式bazel run/bazel test需要本机已安装 Bazel 且仓库的 MODULE.bazel 依赖如rules_java、JUnit、Truth 断言库可正常拉取。结语.gemini/SKILL.md用 8 项技能回答了一个朴素却重要的问题算法教学仓库里的代码如何做到既正确又易教答案是一套完整的工程纪律——用五要素 doc comment 和文件头注释承载教学用五类用例 句读式命名 场景化注释的测试体系承载证明用短名、统一 Big-O 记法、杜绝 Streams 承载一致用提前返回与克制合并承载简洁再用差一错误、负环污染等陷阱清单承载防御。当前仓库的图论、DP、数据结构源码与测试正是这套纪律的忠实样本阅读 BellmanFordAdjacencyList.java 你看到的是规范的文档与 main 位置打开 BellmanFordAdjacencyListTest.java 你看到的是规范的测试覆盖对比 EditDistanceIterative.java 与 EditDistanceRecursive.java 你看到的是规范的重构取舍。将这些约定迁移到你自己的算法项目便是让代码从能运行走向能教学的第一步。赞分享示例工程【免费下载链接】algorithmsA collection of algorithms and data structures项目地址https://gitcode.com/gh_mirrors/algorithms39/algorithms点击查看免费下载相关推荐Hermes Agent深度解析打造个人AI助手的终极指南Hermes Agent深度解析打造个人AI助手的终极指南 Hermes Agent是一款由Nous Research开发的自进化AI智能体支持跨平台部署和AI Agent人工智能AI 应用工具调用Agent 记忆交互助手RAG任务调度MCP 服务javascript-algorithms 仓库实战指南从安装、测试到 JSDoc 文档构建与贡献规范javascript algorithms 仓库实战指南从安装、测试到 JSDoc 文档构建与贡献规范 本指南以 readme.md https://linkERUPT代码质量测试覆盖率与代码规范ERUPT代码质量测试覆盖率与代码规范 ? 痛点低代码框架的质量保障挑战 在企业级低代码开发框架中代码质量往往是最容易被忽视但至关重要的环节。开发者常常面后端低代码AI 应用人工智能AI Agent认证鉴权RAG上一篇终极指南ta-lib-python开源协议解析与BSD许可证详解 下一篇探索ShaderGlass的5个高级应用场景从创意设计到专业工作流创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考