mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
site.py now lists a SKILL.md under skills/ only when /<name>.md is that file byte for byte and every file it points at by a relative path (references/, scripts/, templates/, tools/, a sibling page) is published. 120 entries pointed at files the site does not serve, reference docs were listed as skills, and 18 names served another file. 188 skills remain. tests/discovery.py holds the published index to the same rule. build.py deletes every page it did not write, except the hand-written pages in KEEP, walks skills/ in name order so a shared name resolves the same on every filesystem, and refuses to run without HIPS_DIR. Rebuilt against hanzoai/hips main: the 40 discover-* pages and 20 HIPs whose source is gone are removed, the stale code-review, engineering-code-review and ml pages match their source, and 66 pages that were never built (60 skills among them) and 4 new HIPs are published. .gitignore anchors the root symlinks, so public/gemini.md is not ignored on a case-insensitive checkout.
588 lines
32 KiB
HTML
588 lines
32 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>engineering-code-review</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/engineering-code-review">
|
|
<link rel="alternate" type="text/markdown" href="/engineering-code-review.md">
|
|
<script type="module" src="/webmcp.js"></script>
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/engineering-code-review.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>engineering-code-review</h1><p class="lede">Code review practices, PR etiquette, constructive feedback, automation tools, and effective review workflows</p><h1>Code Review Best Practices</h1>
|
|
<p>The operating process is the release review in <code>skills/code-review/SKILL.md</code>. Machines read the diff. A person decides whether to build it, whether the code is the risky kind, whether it sets a pattern others will copy, whether the evidence is enough, and who owns the outcome. The etiquette below is for those decisions.</p>
|
|
<p><strong>Scope</strong>: Comprehensive guide to code review processes, PR etiquette, constructive feedback, automation, and team collaboration <strong>Lines</strong>: ~350 <strong>Last Updated</strong>: 2025-10-27 <strong>Format Version</strong>: 1.0 (Atomic)</p>
|
|
<hr>
|
|
<h2>When to Use This Skill</h2>
|
|
<p>Activate this skill when:</p>
|
|
<ul><li>Conducting code reviews for pull requests</li><li>Establishing code review standards for a team</li><li>Training engineers on giving and receiving feedback</li><li>Setting up automated review tools (linters, static analysis)</li><li>Defining PR templates and review checklists</li><li>Resolving code review conflicts or disagreements</li><li>Optimizing review turnaround time</li><li>Balancing thoroughness with velocity</li></ul>
|
|
<h2>Core Concepts</h2>
|
|
<h3>Concept 1: The Purpose of Code Review</h3>
|
|
<p><strong>Primary Goals</strong>:</p>
|
|
<ul><li><strong>Catch bugs</strong>: Find logical errors, edge cases, security issues before production</li><li><strong>Knowledge sharing</strong>: Spread understanding of codebase across team</li><li><strong>Maintain quality</strong>: Enforce standards, consistency, best practices</li><li><strong>Mentorship</strong>: Help junior engineers grow through feedback</li><li><strong>Collective ownership</strong>: Everyone responsible for code quality</li></ul>
|
|
<p><strong>Not the Goal</strong>:</p>
|
|
<ul><li>Nitpicking style preferences (use automated formatters)</li><li>Asserting dominance or "being right"</li><li>Rewriting code to match your personal style</li><li>Blocking PRs indefinitely over minor issues</li></ul>
|
|
<h3>Concept 2: Reviewer Responsibilities</h3>
|
|
<p><strong>What to Review</strong>:</p>
|
|
<ol><li><strong>Correctness</strong>: Does the code do what it claims?</li><li><strong>Testing</strong>: Are there adequate tests? Do they cover edge cases?</li><li><strong>Security</strong>: Any vulnerabilities (SQL injection, XSS, auth bypass)?</li><li><strong>Performance</strong>: Any obvious bottlenecks (N+1 queries, unnecessary loops)?</li><li><strong>Maintainability</strong>: Is the code readable and well-structured?</li><li><strong>Documentation</strong>: Are complex parts explained?</li></ol>
|
|
<p><strong>How to Review</strong>:</p>
|
|
<ul><li>Start with the PR description - does it explain the change?</li><li>Review tests first - they document expected behavior</li><li>Read code top-to-bottom, following the logical flow</li><li>Ask questions rather than making demands</li><li>Suggest alternatives, don't just say "this is wrong"</li><li>Approve with minor suggestions rather than blocking</li></ul>
|
|
<h3>Concept 3: Author Responsibilities</h3>
|
|
<p><strong>Before Submitting</strong>:</p>
|
|
<ul><li>Self-review your own code first</li><li>Run tests locally - all passing</li><li>Update documentation if behavior changed</li><li>Keep PRs small (< 400 lines ideal, < 800 max)</li><li>Write clear PR description with context</li></ul>
|
|
<p><strong>During Review</strong>:</p>
|
|
<ul><li>Respond to feedback promptly</li><li>Ask for clarification if feedback is unclear</li><li>Explain your reasoning without being defensive</li><li>Be open to suggestions - reviewers offer valuable perspective</li><li>Push back respectfully when you disagree</li></ul>
|
|
<hr>
|
|
<h2>Patterns</h2>
|
|
<h3>Pattern 1: Effective PR Description Template</h3>
|
|
<p><strong>Good Example</strong>:</p>
|
|
<pre><code class="lang-markdown">## What Changed
|
|
Added user profile photo upload with S3 storage and CloudFront CDN.
|
|
|
|
## Why
|
|
Users have requested profile photos (50+ tickets). Unblocks social
|
|
features planned for Q1 2025.
|
|
|
|
## How
|
|
- New `POST /api/users/:id/photo` endpoint
|
|
- Uploads to S3 bucket `user-photos-prod`
|
|
- CloudFront distribution for fast global delivery
|
|
- Max 5MB file size, JPEG/PNG only
|
|
- Image resized to 400x400px on upload
|
|
|
|
## Testing
|
|
- Unit tests: upload validation, file type checking
|
|
- Integration tests: end-to-end upload flow
|
|
- Manual testing: tested on Chrome, Safari, Mobile Safari
|
|
|
|
## Screenshots
|
|
[Attach screenshot of new feature]
|
|
|
|
## Related
|
|
- Closes #1234
|
|
- Follow-up: Add photo cropping (tracked in #1235)</code></pre>
|
|
<p><strong>Bad Example</strong>:</p>
|
|
<pre><code class="lang-markdown">## What Changed
|
|
Added profile photos.
|
|
|
|
## Testing
|
|
Tested manually, works fine.</code></pre>
|
|
<p><strong>Why Bad</strong>: No context on _why_, no details on implementation, vague testing description.</p>
|
|
<hr>
|
|
<h3>Pattern 2: Constructive Feedback</h3>
|
|
<p><strong>Good Examples</strong>:</p>
|
|
<pre><code class="lang-markdown"># Asking Questions
|
|
❓ What happens if the user uploads a 20MB file? Should we validate
|
|
size on the client side too?
|
|
|
|
# Suggesting Improvements
|
|
💡 Consider extracting this validation logic into a separate function
|
|
for reusability:</code></pre>
|
|
<p>def validate_photo_upload(file): if file.size > 5 <em> 1024 </em> 1024: raise ValidationError("File too large") if file.content_type not in ["image/jpeg", "image/png"]: raise ValidationError("Invalid file type")</p>
|
|
<pre><code>
|
|
# Pointing Out Issues
|
|
⚠️ This could cause a race condition if two uploads happen
|
|
simultaneously. Consider using a unique filename:</code></pre>
|
|
<p>filename = f"{user_id}_{uuid4()}.jpg"</p>
|
|
<pre><code>
|
|
# Praising Good Work
|
|
✅ Nice use of the factory pattern here! Makes testing much easier.</code></pre>
|
|
<p><strong>Bad Examples</strong>:</p>
|
|
<pre><code class="lang-markdown"># Too Vague
|
|
This doesn't look right.
|
|
|
|
# Overly Critical
|
|
This is terrible. Did you even test this?
|
|
|
|
# Nitpicking Without Tools
|
|
Please add spaces around operators. (Use automated formatter instead!)
|
|
|
|
# Making Demands
|
|
Change this to use a factory pattern.
|
|
|
|
# Better Alternative
|
|
Consider using a factory pattern here - it would make testing easier
|
|
and improve separation of concerns. What do you think?</code></pre>
|
|
<hr>
|
|
<h3>Pattern 3: Review Checklist</h3>
|
|
<p><strong>Pre-Merge Checklist</strong>:</p>
|
|
<pre><code class="lang-markdown">## Functionality
|
|
- [ ] Code does what PR description claims
|
|
- [ ] Edge cases handled (null, empty, large inputs)
|
|
- [ ] Error cases handled gracefully
|
|
|
|
## Testing
|
|
- [ ] Unit tests added for new logic
|
|
- [ ] Integration tests for new endpoints
|
|
- [ ] Tests actually test the behavior (not just mocks)
|
|
- [ ] All tests passing in CI
|
|
|
|
## Security
|
|
- [ ] No SQL injection vulnerabilities
|
|
- [ ] Input validation on all user data
|
|
- [ ] Authentication/authorization checked
|
|
- [ ] Sensitive data not logged
|
|
|
|
## Performance
|
|
- [ ] No N+1 query problems
|
|
- [ ] Database queries indexed
|
|
- [ ] No blocking operations in hot paths
|
|
- [ ] Large datasets paginated
|
|
|
|
## Maintainability
|
|
- [ ] Code is readable and well-organized
|
|
- [ ] Complex logic documented
|
|
- [ ] No TODO/FIXME comments (create tickets instead)
|
|
- [ ] Naming is clear and consistent
|
|
|
|
## Documentation
|
|
- [ ] API documentation updated
|
|
- [ ] README updated if needed
|
|
- [ ] Migration guide if breaking change</code></pre>
|
|
<hr>
|
|
<h3>Pattern 4: PR Size Guidelines</h3>
|
|
<p><strong>Ideal PR Sizes</strong>:</p>
|
|
<p>| Size | Lines Changed | Review Time | Quality | |------|---------------|-------------|---------| | Tiny | 1-50 | 5-10 min | Excellent | | Small | 51-200 | 15-30 min | Good | | Medium | 201-400 | 30-60 min | Acceptable | | Large | 401-800 | 1-2 hours | Risky | | Huge | 800+ | 2+ hours | Avoid |</p>
|
|
<p><strong>Breaking Down Large PRs</strong>:</p>
|
|
<pre><code class="lang-python"># Bad: One massive PR
|
|
PR #1: "Implement entire authentication system" (2000 lines)
|
|
- Database models
|
|
- API endpoints
|
|
- Frontend components
|
|
- Tests
|
|
- Documentation
|
|
|
|
# Good: Multiple focused PRs
|
|
PR #1: "Add User and Session database models" (150 lines)
|
|
PR #2: "Add authentication API endpoints" (200 lines)
|
|
PR #3: "Add login/signup UI components" (180 lines)
|
|
PR #4: "Add authentication integration tests" (120 lines)</code></pre>
|
|
<p><strong>Benefits</strong>:</p>
|
|
<ul><li>Faster review turnaround</li><li>More thorough review (not overwhelming)</li><li>Easier to revert if issues found</li><li>Better git history for debugging</li></ul>
|
|
<hr>
|
|
<h3>Pattern 5: Automated Review Tools</h3>
|
|
<p><strong>Pre-Commit Hooks</strong>:</p>
|
|
<pre><code class="lang-yaml"># .pre-commit-config.yaml
|
|
repos:
|
|
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
hooks:
|
|
- id: trailing-whitespace
|
|
- id: end-of-file-fixer
|
|
- id: check-yaml
|
|
- id: check-added-large-files
|
|
|
|
- repo: https://github.com/psf/black
|
|
hooks:
|
|
- id: black # Python formatter
|
|
|
|
- repo: https://github.com/pycqa/flake8
|
|
hooks:
|
|
- id: flake8 # Python linter
|
|
|
|
- repo: https://github.com/pre-commit/mirrors-eslint
|
|
hooks:
|
|
- id: eslint # JavaScript linter</code></pre>
|
|
<p><strong>GitHub Actions CI</strong>:</p>
|
|
<pre><code class="lang-yaml"># .github/workflows/pr-checks.yml
|
|
name: PR Checks
|
|
on: [pull_request]
|
|
|
|
jobs:
|
|
lint:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- name: Run linters
|
|
run: |
|
|
npm run lint
|
|
npm run type-check
|
|
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- name: Run tests
|
|
run: npm test
|
|
|
|
security:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- name: Security scan
|
|
uses: snyk/actions/node@master</code></pre>
|
|
<p><strong>Code Coverage Requirements</strong>:</p>
|
|
<pre><code class="lang-yaml"># codecov.yml
|
|
coverage:
|
|
status:
|
|
project:
|
|
default:
|
|
target: 80% # Fail PR if coverage drops below 80%
|
|
threshold: 2% # Allow 2% decrease</code></pre>
|
|
<hr>
|
|
<h3>Pattern 6: Handling Disagreements</h3>
|
|
<p><strong>Escalation Path</strong>:</p>
|
|
<pre><code>1. Discuss in PR comments
|
|
↓ (if no resolution)
|
|
2. Hop on quick call/screenshare
|
|
↓ (if still no resolution)
|
|
3. Tag tech lead or architect
|
|
↓ (if still no resolution)
|
|
4. Document both approaches, ship one, revisit later</code></pre>
|
|
<p><strong>Example Disagreement Resolution</strong>:</p>
|
|
<pre><code class="lang-markdown"># Original Feedback
|
|
@reviewer: This should use dependency injection instead of direct
|
|
instantiation.
|
|
|
|
# Author Response
|
|
@author: I considered that, but this is a one-off utility function
|
|
that's only called in tests. Adding DI feels like over-engineering.
|
|
What's the specific benefit you see?
|
|
|
|
# Reviewer Clarification
|
|
@reviewer: Fair point. My concern is if we later need to mock this in
|
|
other tests, but you're right that's not needed today. Let's ship this
|
|
and refactor if that need arises. Approved!</code></pre>
|
|
<hr>
|
|
<h2>Best Practices</h2>
|
|
<h3>For Reviewers</h3>
|
|
<ol><li><strong>Review within 24 hours</strong> - Don't block teammates</li><li><strong>Start with what's good</strong> - Praise before criticism</li><li><strong>Be specific</strong> - Link to docs, provide examples</li><li><strong>Ask, don't tell</strong> - "What do you think about X?" vs "Do X"</li><li><strong>Approve with suggestions</strong> - Don't block on minor issues</li><li><strong>Review in small batches</strong> - Better focus, faster feedback</li></ol>
|
|
<h3>For Authors</h3>
|
|
<ol><li><strong>Self-review first</strong> - Catch your own mistakes</li><li><strong>Keep PRs small</strong> - < 400 lines when possible</li><li><strong>Write context</strong> - Help reviewers understand the change</li><li><strong>Respond promptly</strong> - Don't let PRs go stale</li><li><strong>Be grateful</strong> - Reviewers are helping you improve</li><li><strong>Push back respectfully</strong> - You know the code best</li></ol>
|
|
<h3>For Teams</h3>
|
|
<ol><li><strong>Define standards</strong> - Document what to review</li><li><strong>Automate style</strong> - Don't waste human time on formatting</li><li><strong>Rotate reviewers</strong> - Spread knowledge, prevent bottlenecks</li><li><strong>Track metrics</strong> - PR size, review time, bug escape rate</li><li><strong>Celebrate good reviews</strong> - Recognize thorough, helpful feedback</li></ol>
|
|
<hr>
|
|
<h2>Anti-Patterns</h2>
|
|
<h3>Common Mistakes</h3>
|
|
<pre><code>❌ Reviewing 2000-line PRs
|
|
→ Break into smaller PRs
|
|
|
|
❌ Nitpicking style without automation
|
|
→ Use formatters (black, prettier, gofmt)
|
|
|
|
❌ Blocking PRs over minor issues
|
|
→ Approve with suggestions for follow-up
|
|
|
|
❌ Reviewing only for bugs
|
|
→ Also review for maintainability, performance, security
|
|
|
|
❌ Being overly critical without praise
|
|
→ Balance criticism with appreciation
|
|
|
|
❌ Reviewing too slowly (> 48 hours)
|
|
→ Review within 24 hours or reassign
|
|
|
|
❌ Rubber-stamping without reading
|
|
→ Actually review the code
|
|
|
|
❌ Rewriting code to match your style
|
|
→ Respect author's approach if it's reasonable</code></pre>
|
|
<hr>
|
|
<h2>Code Examples</h2>
|
|
<h3>Python: Good vs Bad PR Structure</h3>
|
|
<p><strong>Bad: Too Large</strong>:</p>
|
|
<pre><code class="lang-python"># PR: Implement entire user management system (1500 lines)
|
|
# - User model, authentication, authorization, profile, settings
|
|
# - Impossible to review thoroughly</code></pre>
|
|
<p><strong>Good: Focused PRs</strong>:</p>
|
|
<pre><code class="lang-python"># PR 1: Add User model and migrations (100 lines)
|
|
class User(models.Model):
|
|
email = models.EmailField(unique=True)
|
|
password_hash = models.CharField(max_length=255)
|
|
created_at = models.DateTimeField(auto_now_add=True)
|
|
|
|
# PR 2: Add authentication endpoints (150 lines)
|
|
@api.post("/auth/login")
|
|
def login(email: str, password: str) -> Token:
|
|
user = User.get_by_email(email)
|
|
if not user or not user.verify_password(password):
|
|
raise AuthenticationError()
|
|
return create_token(user.id)
|
|
|
|
# PR 3: Add profile endpoints (120 lines)
|
|
# PR 4: Add integration tests (100 lines)</code></pre>
|
|
<hr>
|
|
<h3>Go: Reviewable Test Structure</h3>
|
|
<p><strong>Bad: Unclear Test</strong>:</p>
|
|
<pre><code class="lang-go">func TestUser(t *testing.T) {
|
|
// What is this testing?
|
|
u := User{Email: "[email protected]"}
|
|
if u.Email != "[email protected]" {
|
|
t.Fail()
|
|
}
|
|
}</code></pre>
|
|
<p><strong>Good: Clear Test with Table-Driven Approach</strong>:</p>
|
|
<pre><code class="lang-go">func TestUserEmailValidation(t *testing.T) {
|
|
tests := []struct {
|
|
name string
|
|
email string
|
|
wantErr bool
|
|
}{
|
|
{name: "valid email", email: "[email protected]", wantErr: false},
|
|
{name: "missing @", email: "userexample.com", wantErr: true},
|
|
{name: "empty", email: "", wantErr: true},
|
|
}
|
|
|
|
for _, tt := range tests {
|
|
t.Run(tt.name, func(t *testing.T) {
|
|
u := User{Email: tt.email}
|
|
err := u.Validate()
|
|
if (err != nil) != tt.wantErr {
|
|
t.Errorf("got error %v, wantErr %v", err, tt.wantErr)
|
|
}
|
|
})
|
|
}
|
|
}</code></pre>
|
|
<hr>
|
|
<h3>TypeScript: Reviewable Component Structure</h3>
|
|
<p><strong>Bad: God Component</strong>:</p>
|
|
<pre><code class="lang-typescript">// Bad: 800-line component doing everything
|
|
export function UserDashboard() {
|
|
// Authentication logic
|
|
// Data fetching
|
|
// Form handling
|
|
// Validation
|
|
// Rendering
|
|
// Hard to review!
|
|
}</code></pre>
|
|
<p><strong>Good: Separated Concerns</strong>:</p>
|
|
<pre><code class="lang-typescript">// Good: Small, focused components
|
|
export function UserDashboard() {
|
|
const { user } = useAuth();
|
|
const { profile, loading } = useUserProfile(user.id);
|
|
|
|
if (loading) return <LoadingSpinner />;
|
|
|
|
return (
|
|
<div>
|
|
<ProfileHeader profile={profile} />
|
|
<ProfileForm profile={profile} onSave={handleSave} />
|
|
</div>
|
|
);
|
|
}
|
|
|
|
// Each component is small, testable, reviewable</code></pre>
|
|
<hr>
|
|
<h2>Level 3: Resources</h2>
|
|
<p>For deep-dive learning and production-ready tools, see the <code>resources/</code> directory:</p>
|
|
<h3>Reference Materials</h3>
|
|
<ul><li><strong>REFERENCE.md</strong> (~900 lines): Comprehensive code review guide</li><li>Complete review checklist (design, functionality, complexity, tests, naming, comments)</li><li>Writing effective review comments (tone, structure, severity levels)</li><li>Handling disagreements and conflict resolution</li><li>Common code smells and fixes</li><li>Review automation (linters, formatters, security scanners for Python, JavaScript, TypeScript, Rust, Go)</li><li>GitHub PR workflows and branch protection</li><li>Review metrics (turnaround time, review depth, defect escape rate)</li></ul>
|
|
<h3>Scripts (<code>resources/scripts/</code>)</h3>
|
|
<ul><li><strong>review_pr.py</strong>: Automated PR review script</li><li>Runs linters, checks tests, analyzes diff</li><li>Detects common issues (debug statements, secrets, TODOs)</li><li>Generates human or JSON reports</li><li>CLI: <code>./review_pr.py --base main --json</code></li></ul>
|
|
<ul><li><strong>analyze_review_metrics.py</strong>: GitHub PR metrics analyzer</li><li>Tracks turnaround time, review depth, iteration count</li><li>Reviewer leaderboard</li><li>PR size distribution</li><li>CLI: <code>./analyze_review_metrics.py --repo owner/repo --days 30 --json</code></li></ul>
|
|
<ul><li><strong>generate_review_checklist.sh</strong>: Custom checklist generator</li><li>Creates checklists by PR type (feature, bugfix, security, refactor, docs)</li><li>Language-specific checks (Python, JavaScript, TypeScript, Rust, Go)</li><li>Markdown or JSON output</li><li>CLI: <code>./generate_review_checklist.sh --type security --lang python --output checklist.md</code></li></ul>
|
|
<h3>Examples (<code>resources/examples/</code>)</h3>
|
|
<ul><li><strong>github/PULL_REQUEST_TEMPLATE.md</strong>: Production-ready PR template</li><li><strong>github/code-review-workflow.yml</strong>: Complete GitHub Actions workflow</li><li>Linting, security scanning, test execution</li><li>PR size analysis with automated comments</li><li>Reviewer assignment based on CODEOWNERS</li><li><strong>python/automated_review_checks.py</strong>: Python code reviewer</li><li>Checks imports, function length, complexity, documentation, naming, anti-patterns, security</li><li><strong>checklists/security-review.md</strong>: Comprehensive security checklist</li><li>Authentication, authorization, input validation, data protection, common vulnerabilities</li><li><strong>checklists/performance-review.md</strong>: Performance optimization checklist</li><li>Database queries, algorithms, memory, network I/O, frontend performance</li></ul>
|
|
<p>All scripts are executable, documented, and production-ready.</p>
|
|
<hr>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><strong>engineering-code-quality</strong>: SOLID principles, code smells, metrics</li><li><strong>engineering-refactoring-patterns</strong>: When and how to refactor</li><li><strong>engineering-test-driven-development</strong>: Writing testable code</li><li><strong>engineering-technical-debt</strong>: Managing and prioritizing tech debt</li><li><strong>engineering-continuous-integration</strong>: Automating review checks</li></ul>
|
|
<hr>
|
|
<h2>References</h2>
|
|
<ul><li><a href="https://google.github.io/eng-practices/review/">Google Engineering Practices</a></li><li><a href="https://learn.microsoft.com/en-us/azure/devops/repos/git/review-pull-requests">Microsoft Code Review Guidelines</a></li><li><a href="https://conventionalcomments.org/">Conventional Comments</a></li><li><a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests">GitHub PR Best Practices</a></li></ul>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/engineering-code-review.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |