- Don't repeat yourself. Avoid copy-and-paste. Constantly move code and extract to constants/functions.
- Avoid using
useEffectfor pure state transformations.- BAD ❌:
useEffect(() => { const result = somePureComputation(someState); setTransformedState(result); }, [someState]); - Good ✔️:
const transformedResult = somePureComputation(someState);
- BAD ❌:
- DO NOT add
<style>elements orstyleproperty. Inline Tailwind classes instead. - DO NOT write
@media (max-width: 767px) { ... }. Use Tailwind breakpoint prefixes likemdormax-mdinstead. - Only modify
src/styles/global.cssto define utilities or add generic, widely used styles like those for prose. Use variant rules like@variant md { ... }or@variant max-md { ... }for media width queries. - Always use responsive units. Specify size in
remto icons, e.g.<IconWorld size="1.25rem" />.
- All translation strings must be placed inside the
src/i18ndirectory. - Translation locales should be sorted in alphabetical order.
- When defining translations, wrap a locale-keyed object with the
makeResourcemethod from@/i18n/utils. If you supply an object to the generic type parameter ofmakeResource, it must be atype, not aninterface. WARNING: Supplying aninterfacewill result in a TypeScript error. - Use
I18n.localesfrom@/i18n/utilsto get a list of all locales. - DO NOT inline "yue". Use
I18n.defaultLocalefrom@/i18n/utils.
Reactis implicitly imported as type. Directly use types likeReact.FCand etc. Only import individual named exports as values.- BAD ❌:
import type React from "react"; - BAD ❌:
import type { FC } from "react"; - BAD ❌:
import React from "react"; - Good ✔️:
import { useState } from "react";
- BAD ❌:
- Type-only imports MUST be prefixed by
type.- BAD ❌:
import { Locale } from "@/i18n/utils"; - Good ✔️:
import type { Locale } from "@/i18n/utils";
- BAD ❌:
- Add comments sparsely. Comments should be added solely for explaining code.
- GOOD ✔️:
// Do not split at fullwidth spaces, which are useful in lyrics - GOOD ✔️:
// Find the topmost visible heading based on intersection ratio and position - GOOD ✔️:
// Setup observer slightly delayed to ensure elements are in the DOM - GOOD ✔️:
// Handle edge case: ...
- GOOD ✔️:
- DO NOT add meta-commentary, i.e. comments about the action you have just performed.
- BAD ❌:
// Added ... - BAD ❌:
// Modified ... - BAD ❌:
// Adjusted ... - BAD ❌:
// Changed ... - BAD ❌:
// Removed ... - BAD ❌:
// Copied from ... - BAD ❌:
// Replaced ... with ... - BAD ❌:
// Use ... instead of ... - BAD ❌:
// Define ...
- BAD ❌:
- DO NOT add comments hinting next steps. Recommendations should stay in the conversation.
- BAD ❌:
{/* Adjust styles as needed */} - BAD ❌:
{/* Add other props if necessary */}
- BAD ❌:
- DO NOT add file names to the top of a file.
- BAD ❌:
// src/utils.ts - BAD ❌:
// src/index.astro
- BAD ❌:
- Avoid self-explanatory comments. Only add comments if the code is not obvious.
- BAD ❌:
import React from "react"; // Import React - BAD ❌:
return I18n.locales.filter((locale) => locale !== I18n.defaultLocale) // Exclude default locale - BAD ❌:
observer.disconnect(); // Disconnect observer on cleanup
- BAD ❌:
- Within a large block of JSX, add labels sparsely.
- GOOD ✔️:
{/* Header */} - GOOD ✔️:
{/* Main Container */}
- GOOD ✔️:
- If variable names can explain code, avoid commenting.
- BAD ❌:
const translationEn = headingTranslations.en; // Get English translations for slug generation - GOOD ✔️:
const translationForSlugGeneration = headingTranslations.en;
- BAD ❌:
- When removing code, eliminate entirely. DO NOT comment out code.