docs: replace "no comments" rule with required one-line function summary

[Copilot]

The existing "No Comments" policy assumed full codebase familiarity, making it hard for developers to navigate unfamiliar code quickly.

Changes

• Philosophy — updated to state that every function must have a brief comment describing its purpose
• Section 1 (Comments Policy) — rewritten from "No Comments (Self-Documenting Code)" to "One-Line Function Summary Required":
  • Comment goes immediately above the function, one sentence, starts with a verb
  • Describes what the function does, not how
  • Inline body comments are still discouraged — refactor instead
• All code examples — updated throughout the document so every "GOOD" snippet demonstrates the convention

// BAD: no comment
function calculateDiscountedPrice(orderTotal: number, itemPrice: number): number { ... }

// GOOD: one-line summary above
// Calculates the final price of an item after applying an order-size discount.
function calculateDiscountedPrice(orderTotal: number, itemPrice: number): number { ... }

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[cloudflare-workers-and-pages]

Deploying internal-docs with    Cloudflare Pages

Latest commit:	6ae1ed7
Status:	✅  Deploy successful!
Preview URL:	https://0f87d49f.internal-docs-ai1.pages.dev
Branch Preview URL:	https://copilot-update-docs-coding-c.internal-docs-ai1.pages.dev

View logs