mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
587 lines
31 KiB
HTML
587 lines
31 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="alternate" type="text/markdown" href="/engineering-code-review.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/engineering-code-review">
|
|
</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><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> |