# Code Style Guide

What we expect for labs, homework, and the capstone. Auto-graders check structure; reviewers check style. Both matter.

## General

- **One thing per file.** A page = one HTML file, its styles in one CSS file, its scripts in one JS file (split as the project grows).
- **Indent with 2 spaces.** Never mix tabs and spaces.
- **End files with a newline.**
- **No trailing whitespace.**
- **UTF-8** encoding everywhere.
- **LF** line endings. (Configure: `git config --global core.autocrlf input` on Mac/Linux, `true` on Windows.)
- **Format on save** with Prettier (VS Code: `editor.formatOnSave: true`).

## HTML

- Always `<!DOCTYPE html>`, `<html lang="en">`, `<meta charset="UTF-8">`, `<meta name="viewport" ...>`.
- Use **semantic** elements (`<header>`, `<main>`, `<nav>`, `<section>`, `<article>`, `<footer>`) over `<div>`.
- One `<h1>` per page. Don't skip heading levels.
- Every `<img>` needs `alt`.
- Every form control needs an associated `<label>`.
- Lowercase tag and attribute names.
- Double-quote attribute values.
- Validate at <https://validator.w3.org/> — your page should produce **zero** errors.

## CSS

- External stylesheet only — no `<style>` blocks or `style=""` attributes in submitted work (unless the lab says otherwise).
- One selector per line, opening brace on the same line:
  ```css
  .card,
  .panel {
    padding: 1rem;
  }
  ```
- Property order: positioning → box → typography → visual → misc.
- Use **rem** for typography and spacing; **px** sparingly.
- Use **CSS variables** (`--primary`) for colours and recurring values.
- Class names: `kebab-case`. Don't style by ID.
- Avoid `!important`.
- Mobile-first media queries: write base styles for small screens, add `@media (min-width: ...)` for larger.

## JavaScript

- `const` by default; `let` if reassigning. Never `var`.
- `===` and `!==`. Never `==`.
- `camelCase` for variables/functions, `PascalCase` for classes/components, `UPPER_SNAKE_CASE` for true constants.
- Arrow functions for callbacks; named functions for top-level.
- Modules: one component/feature per file. Use `import`/`export`, not globals.
- No `console.log` in submitted code (use it while debugging, remove before commit).
- Use `textContent`, not `innerHTML`, when inserting user data (XSS).
- Always handle Fetch errors:
  ```js
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  ```

## React

- Functional components only.
- One component per file; filename = component name (`UserCard.jsx`).
- Props destructured in the signature: `function Card({ title, children })`.
- Hooks at the top of the component, before any return.
- Stable `key` on list items — never the array index for dynamic lists.
- Co-locate component-specific CSS or use CSS Modules.

## Java / Spring Boot

- Follow Google Java Style: <https://google.github.io/styleguide/javaguide.html>.
- 4-space indent (Java convention).
- Package per layer: `controller`, `service`, `repository`, `model`, `dto`.
- Constructor injection (no `@Autowired` on fields).
- Use DTOs for request/response — don't expose JPA entities directly.

## Python / Django

- Follow PEP 8: <https://peps.python.org/pep-0008/>.
- Use `black` to auto-format and `ruff` to lint.
- Snake_case for variables and functions, PascalCase for classes.

## Git

- Commit message: `Imperative subject under 72 chars` then a blank line and details if needed.
  - ✓ `Add hero section to homepage`
  - ✗ `added stuff`, `fixed bug`, `wip`
- Commit early and often. Push at least once per work session.
- One logical change per commit.
- Never commit secrets, `node_modules/`, `target/`, build output, or `.env` files.

## Folder layout (general)

```
project/
├─ README.md
├─ .gitignore
├─ index.html             # frontend entry
├─ styles/
│  └─ main.css
├─ scripts/
│  └─ app.js
└─ assets/
   └─ images/
```

For Node/React projects, follow the framework's convention (Vite scaffolds the right structure).

## README

Every lab/homework repo must have a `README.md` with:

1. **Name & description** — what is this?
2. **How to run** — exact commands (`npm install && npm run dev`).
3. **Features** — what works.
4. **Known issues** — what doesn't.
5. **Author** — your name + email.

## Auto-checks before you push

- [ ] Page loads with no console errors
- [ ] Validator passes (HTML and CSS)
- [ ] No commented-out blocks of dead code
- [ ] No `console.log` left over
- [ ] README is up-to-date
- [ ] `.env` and secrets are NOT committed
