TECH **Git & GitHub: Code Review Comments & Suggestions (`suggestion`)**

Git & GitHub: Code Review Comments & Suggestions (suggestion)

Hyper-practical, zero-fluff guide for engineers who need to review code efficiently, leave actionable feedback, and automate fixes.

1. What This Is & Why It Matters

You’re a backend engineer on a team of 10. A junior dev opens a PR to refactor an API endpoint. Their code works, but: - They hardcoded a timeout value (30) instead of using the config file.
- They duplicated a validation function that already exists in a shared module.
- Their error messages are unclear ("Failed" instead of "Failed to fetch user data: {error}").

Without suggestion blocks in GitHub PR reviews:
- You write a comment: "Use the config file for timeouts." The dev manually edits the file, pushes a new commit, and you re-review. This back-and-forth wastes 30+ minutes per PR.
- The dev might miss your comment entirely, merge the PR, and introduce a bug that surfaces in production.

With suggestion blocks:
- You highlight the line, click "Add a suggestion", and GitHub generates a diff that the dev can apply with one click.
- The PR is fixed in seconds, and you move on to higher-value work.

Why this matters in production:
- Faster merges: Reduce PR cycle time by 50%+ (real data from teams at Microsoft, Google, and startups).
- Fewer bugs: Automated fixes mean fewer human errors (e.g., typos, missed changes).
- Better onboarding: Junior devs learn faster when they see exactly how to fix issues.
- Audit trail: Suggestions are preserved in the PR history, so future maintainers understand why a change was made.

Real-world scenario:
You’re the tech lead for a fintech app. A PR introduces a SQL query that’s vulnerable to injection. Instead of writing a long comment explaining parameterized queries, you: 1. Highlight the line.
2. Add a suggestion block with the fixed query.
3. The dev applies it, and the PR is safe to merge—no risk of the vulnerability slipping through.

2. Core Concepts & Components

1. suggestion Block

• Definition: A GitHub PR review feature that lets you propose a specific code change as a diff. The author can apply it with one click.
• Production insight: If you’re not using suggestions, you’re wasting time on manual fixes. Teams at FAANG use this to enforce coding standards at scale.

2. Markdown Syntax for Suggestions

• Definition: Suggestions are written in Markdown with triple backticks and the suggestion language tag: markdown ```suggestion // Your proposed code here ```
• Production insight: If you forget the suggestion tag, GitHub won’t render the diff, and the author can’t apply it.

3. Multi-Line Suggestions

• Definition: You can suggest changes spanning multiple lines by highlighting a block of code.
• Production insight: Useful for refactoring entire functions or fixing complex logic. Example: ```python # Before def validate_input(data):
  if not data:
  return False
  return True

# After (suggestion) def validate_input(data):
if not isinstance(data, dict) or not data:
raise ValueError("Invalid input: must be a non-empty dict")
return True ```

4. Suggesting File-Level Changes

• Definition: You can suggest adding, removing, or renaming entire files (e.g., moving a config file to the correct directory).
• Production insight: Rarely used but powerful for enforcing project structure (e.g., "This file belongs in/tests/unit/").

5. Suggestions with Context

• Definition: Combine suggestions with explanatory comments to teach best practices.
• Production insight: Junior devs learn faster when they see why a change is needed. Example: markdown This query is vulnerable to SQL injection. Always use parameterized queries:suggestion cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))

6. Suggestions in Code Reviews vs. Direct Commits

• Definition:
• Code review suggestions: Applied by the PR author (or a maintainer) via the GitHub UI.
• Direct commits: You can commit suggestions directly to the branch if you have write access.
• Production insight: Direct commits are faster but bypass review—only use them for trivial fixes (e.g., typos).

7. Suggestions and CI/CD

• Definition: Suggestions can trigger CI pipelines (e.g., GitHub Actions) to run tests on the proposed changes before they’re applied.
• Production insight: Prevents broken builds by validating suggestions early. Example workflow: yaml # .github/workflows/suggestion-tests.yml on: [pull_request_review] jobs:
test-suggestions:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm test

8. Suggestions and Security

• Definition: Never suggest secrets (API keys, passwords) in code reviews—even as a placeholder.
• Production insight: GitHub scans PRs for secrets. If you accidentally leak one, rotate it immediately.

9. Suggestions and Git Blame

• Definition: When a suggestion is applied, Git attributes the change to the original author (not you).
• Production insight: Preserves the blame history, so future devs know who wrote the code (not who suggested the fix).

10. Suggestions and Team Culture

• Definition: Suggestions should be collaborative, not punitive. Use them to teach, not shame.
• Production insight: Teams that use suggestions report higher psychological safety (source: Google’s Project Aristotle).

3. Step-by-Step: Leaving and Applying Suggestions

Prerequisites

• A GitHub account with access to a repository.
• A PR open for review (or create one: git checkout -b fix/timeout-bug && git push origin fix/timeout-bug).
• Basic familiarity with GitHub’s PR interface.

Task: Fix a Hardcoded Timeout in a PR

Scenario: A teammate opened a PR to add a new API endpoint, but they hardcoded a timeout value (30) instead of using the config file.

Step 1: Open the PR in GitHub

1. Navigate to the repository on GitHub.
2. Click "Pull requests" > Select the PR.
3. Click the "Files changed" tab.

Step 2: Highlight the Problematic Code

1. Find the line with the hardcoded timeout:
   python
timeout = 30 # Hardcoded! Should use config.TIMEOUT
2. Click the "..." (ellipsis) next to the line number.
3. Select "Add a suggestion".

Step 3: Write the Suggestion

GitHub auto-generates a suggestion block. Replace the code with your fix:

```suggestion
timeout = config.TIMEOUT
```

Add a comment explaining why:

Use the config file for timeouts to ensure consistency across environments.

Step 4: Submit the Review

1. Click "Add single comment" (or "Start a review" if you have more feedback).
2. If starting a review, click "Finish your review" > "Request changes" or "Comment".

Step 5: The Author Applies the Suggestion

1. The PR author sees your suggestion in the "Conversation" tab.
2. They click "Commit suggestion" > "Commit changes".
3. The fix is applied to their branch without a new commit.

Step 6: Verify the Fix

1. Refresh the "Files changed" tab.
2. Confirm the line now reads:
   python
timeout = config.TIMEOUT

Step 7: Approve the PR

1. If the fix is correct, click "Review changes" > "Approve".
2. Merge the PR.

4. ? Production-Ready Best Practices

Security

• Never suggest secrets: If a PR accidentally exposes a secret (e.g., API_KEY = "123"), do not suggest a fix—comment "@author please rotate this key immediately and use GitHub Secrets."
• Use environment variables: For config values, suggest: suggestion timeout = os.getenv("TIMEOUT", 30)
• Validate suggestions in CI: Add a GitHub Action to run git-secrets or trufflehog on PRs to catch accidental leaks.

Cost Optimization

• Avoid "drive-by" suggestions: Every suggestion should have a clear ROI (e.g., fixing a bug, improving performance). Don’t suggest style nitpicks unless they’re part of the team’s agreed-upon linter rules.
• Batch suggestions: If a file has 10 typos, suggest them all in one comment instead of 10 separate ones.

Reliability & Maintainability

• Use templates for common fixes: Create a team cheat sheet for frequent suggestions (e.g., "Useasync/awaitinstead of.then()").
• Link to docs: If a suggestion references a team standard, link to the internal wiki: markdown This violates our [error handling guidelines](https://wiki.example.com/error-handling). Here's the fix:suggestion raise ValueError(f"Invalid input: {data}")
• Tag the right people: If a suggestion requires domain knowledge (e.g., database changes), tag a subject-matter expert: markdown @db-team Can you review this query optimization?suggestion SELECT * FROM users WHERE id = %s

Observability

• Track suggestion metrics: Use GitHub’s API to measure:
• Average time to merge PRs with suggestions vs. without.
• Number of suggestions per PR (aim for <5 to avoid overwhelming authors).
• Monitor for "suggestion fatigue": If a dev gets the same suggestion repeatedly, pair with them to fix the root cause (e.g., add a linter rule).

5. ⚠️ Common Mistakes & Traps

6. ? Exam/Certification Focus

GitHub certifications (e.g., GitHub Actions, GitHub Administration) and DevOps interviews often test your ability to: - Use suggestions to enforce coding standards.
- Automate fixes with GitHub Actions.
- Collaborate efficiently in PRs.

Typical Question Patterns

1. Scenario: "A PR introduces a hardcoded API endpoint. How do you propose a fix?"
2. Answer: Use a suggestion block to replace the hardcoded value with an environment variable.

3. Trap: Suggesting a direct commit (bypasses review).

4. Scenario: "A teammate keeps making the same style mistake (e.g., camelCase instead of snake_case). How do you enforce consistency?"

5. Answer: Add a linter rule (e.g., ESLint, Pylint) and suggest fixes in PRs until the rule is added.

6. Trap: Manually suggesting the same fix repeatedly (not scalable).

7. Scenario: "A PR exposes a secret. What’s your next step?"

8. Answer: Comment "@author please rotate this key immediately and use GitHub Secrets." Do not suggest a fix.
9. Trap: Suggesting a placeholder (e.g., API_KEY = "REDACTED") without addressing the leak.

Key ⚠️ Trap Distinctions

7. ? Hands-On Challenge

Challenge:
A teammate opened a PR to add a new feature, but their error handling is inconsistent. They use:

if not user:
    return None

in some places and:

if not user:
    raise ValueError("User not found")

in others. Suggest a fix to standardize the error handling.

Solution:
1. Highlight the first example.
2. Add a suggestion:
markdown
Let's standardize on raising exceptions for consistency:
```suggestion
if not user:
raise ValueError("User not found")
``` 3. Add a comment: "This matches our [error handling guidelines](https://wiki.example.com/error-handling)."

Why it works:
- Enforces consistency across the codebase.
- Links to team standards for future reference.
- The author can apply the fix with one click.

8. ? Rapid-Reference Crib Sheet

9. ? Where to Go Next

1. GitHub Docs: Reviewing Proposed Changes – Official guide to suggestions.
2. GitHub Actions for PR Reviews – Automate suggestion testing.
3. Google’s Engineering Practices: Code Review – How Google uses suggestions at scale.
4. GitHub CLI (gh) for PR Reviews – Review PRs from the terminal.