|
| 1 | +# Coding Guidelines |
| 2 | + |
| 3 | +## Core Development Principles |
| 4 | + |
| 5 | +- **Keep It Simple:** Write clean, direct code without clever tricks. Favor readability over cleverness. Code like Hemingway would - simple and direct. |
| 6 | +- **Use Modern JavaScript:** No TypeScript - use JavaScript with JSDoc types. Use ES Modules and modern ES6+ features that improve clarity (destructuring, template literals, etc.) |
| 7 | +- **Self-Documenting Code:** Use meaningful variable and function names that explain their purpose. Make code intention-revealing with clear naming and structure. |
| 8 | +- **Bottom-Line-Up-Front Logic:** Place core logic early in functions. Return early rather than nesting deeply. Handle primary cases first, edge cases second. |
| 9 | +- **Don't Repeat Yourself...twice (DRYT):** Abstract logic repeated more than once into shared functions. Create a single source of truth for each piece of functionality. |
| 10 | +- **You Aren't Gonna Need It (YAGNI):** Avoid premature abstraction or coding for hypothetical future requirements. |
| 11 | +- **One Responsibility:** Write small, focused functions and modules that do one thing well. |
| 12 | + |
| 13 | +## Project-Specific Standards |
| 14 | + |
| 15 | +- Indent with tabs |
| 16 | +- Always add JSDoc types |
| 17 | +- Use TDD: write failing tests first, then code that passes |
| 18 | +- Log changes in CHANGELOG.md when functionality is added or removed |
| 19 | +- For DOM interaction, always use web components |
| 20 | +- Use functional programming for data transformations, OOP for large control flow structures |
| 21 | +- Avoid Windows-specific tools (rimraf, cross-env, mkdirp) |
| 22 | +- Traditional control structures (if/else, switch, while) are acceptable |
| 23 | +- Support all modern browsers. IE is not supported |
| 24 | +- Everything must be covered by end-to-end Playwright browser tests |
| 25 | +- Prefer long flat directories |
| 26 | +- Do not create functions for the sake of organization; functions are for code reuse |
| 27 | +- If a function isn't passed as a callback, or have at least two callsites, then it doesn't need to exist |
| 28 | + |
| 29 | +## HTML & CSS Guidance |
| 30 | + |
| 31 | +- **Semantic Structure:** Use proper HTML5 semantic elements over generic divs |
| 32 | +- **Lean Markup:** Include only the necessary HTML, avoid extra wrappers |
| 33 | +- **Separation of Concerns:** Keep structure (HTML) separate from presentation (CSS) |
| 34 | +- **Simple Selectors:** Avoid deeply nested CSS selectors |
| 35 | +- **Mobile-First Design:** Start with mobile layouts and enhance for larger screens |
| 36 | +- **Progressive Enhancement:** Ensure core functionality works without JavaScript |
| 37 | + |
| 38 | +## Accessibility & Web Best Practices |
| 39 | + |
| 40 | +- **WCAG Compliance:** Follow accessibility guidelines (WCAG) for all components |
| 41 | +- **Keyboard Navigation:** Ensure all interactive elements are keyboard accessible |
| 42 | +- **Screen Reader Support:** Use appropriate ARIA attributes and semantic HTML |
| 43 | +- **Reduced Motion:** Respect user preferences with prefers-reduced-motion media query |
| 44 | +- **Performance Optimization:** Minimize asset sizes and optimize for Core Web Vitals |
| 45 | + |
| 46 | +## Console Logging Guidelines |
| 47 | + |
| 48 | +- Use emojis in console messages and test names 🚀 |
| 49 | +- Include two emojis per message: one shared across the file, one unique |
| 50 | +- Use console methods in important locations as a form of documentation: |
| 51 | + - `console.debug()`: For very minor info or code in loops |
| 52 | + - `console.info()`: For non-critical information |
| 53 | + - `console.log()`: For information users may want to see |
| 54 | + - `console.warn()`: For information users NEED to see |
| 55 | + - `console.error()`: Only for unrecoverable errors |
| 56 | + include any local variables that might be useful for debugging purposes |
0 commit comments