front-end-dev-standards 1.0.0 → 1.1.0

package/standards//360/237/247/221/342/200/215/360/237/222/273 coding-style.md"

@@ -0,0 +1,765 @@
+# Coding Standards
+
+Version: 1.0
+Target: Angular 20+
+Language: TypeScript 5+
+Applies To: All Frontend Applications
+
+---
+
+# 1. Coding Principles
+
+## Core Principles
+
+1. Readability over cleverness
+2. Simplicity over complexity
+3. Consistency over personal preference
+4. Explicit over implicit
+5. Composition over inheritance
+6. Strong typing over shortcuts
+7. Maintainability over speed of implementation
+
+---
+
+# 2. Clean Code Rules
+
+## Functions
+
+### Must
+
+* Have a single responsibility
+* Be small and focused
+* Have descriptive names
+* Return one type consistently
+
+Good:
+
+```typescript
+calculateWeeklyHours(entries: TimesheetEntry[]): number
+```
+
+Bad:
+
+```typescript
+calc(data: any): any
+```
+
+---
+
+## Function Size
+
+Recommended:
+
+```text
+5 - 30 lines
+```
+
+Maximum:
+
+```text
+50 lines
+```
+
+Refactor beyond this.
+
+---
+
+## Nesting
+
+Maximum nesting level:
+
+```text
+3 levels
+```
+
+Bad:
+
+```typescript
+if (...) {
+  if (...) {
+    if (...) {
+      if (...) {}
+    }
+  }
+}
+```
+
+Prefer guard clauses.
+
+---
+
+# 3. TypeScript Standards
+
+## Strict Mode
+
+Required:
+
+```json
+{
+  "strict": true,
+  "noImplicitReturns": true,
+  "noImplicitOverride": true,
+  "noUncheckedIndexedAccess": true,
+  "exactOptionalPropertyTypes": true
+}
+```
+
+---
+
+## Type Rules
+
+### Prefer Interface
+
+```typescript
+interface Employee {
+  id: string;
+}
+```
+
+### Use Type For
+
+```typescript
+type Status =
+  | 'active'
+  | 'inactive';
+```
+
+### Never Use
+
+```typescript
+any
+```
+
+Use:
+
+```typescript
+unknown
+```
+
+with type guards.
+
+---
+
+## Explicit Return Types
+
+Required for:
+
+* Public methods
+* Services
+* Utility functions
+
+Example:
+
+```typescript
+getEmployee(id: string): Observable<Employee>
+```
+
+---
+
+## Readonly First
+
+```typescript
+readonly employees =
+  signal<Employee[]>([]);
+```
+
+Use readonly whenever mutation is not required.
+
+---
+
+# 4. Naming Conventions
+
+## Classes
+
+```typescript
+EmployeeService
+TimesheetStore
+AttendanceGuard
+```
+
+---
+
+## Interfaces
+
+```typescript
+Employee
+TimesheetEntry
+```
+
+Never:
+
+```typescript
+IEmployee
+```
+
+---
+
+## Signals
+
+```typescript
+loading
+employees
+selectedEmployee
+```
+
+Boolean signals:
+
+```typescript
+isLoading
+hasError
+canEdit
+```
+
+---
+
+## Observables
+
+```typescript
+employees$
+user$
+permissions$
+```
+
+Must use `$` suffix.
+
+---
+
+## Constants
+
+```typescript
+MAX_RETRY_COUNT
+DEFAULT_PAGE_SIZE
+```
+
+---
+
+## Enums
+
+Prefer union types.
+
+Avoid:
+
+```typescript
+enum Status {}
+```
+
+Prefer:
+
+```typescript
+type Status =
+  | 'active'
+  | 'inactive';
+```
+
+---
+
+# 5. Angular Coding Standards
+
+## Component Rules
+
+Every component must:
+
+* Be standalone
+* Use OnPush
+* Use inject()
+* Use signals
+
+Example:
+
+```typescript
+@Component({
+  standalone: true,
+  changeDetection:
+    ChangeDetectionStrategy.OnPush
+})
+```
+
+---
+
+## Member Order
+
+1. inject()
+2. input()
+3. output()
+4. signals
+5. computed
+6. effects
+7. lifecycle hooks
+8. public methods
+9. private methods
+
+---
+
+# 6. Import Standards
+
+Order imports:
+
+```typescript
+Angular
+Angular Material
+RxJS
+Third Party
+Core
+Shared
+Feature
+Relative
+```
+
+Example:
+
+```typescript
+import { Component } from '@angular/core';
+
+import { MatButtonModule } from '@angular/material/button';
+
+import { Observable } from 'rxjs';
+
+import { EmployeeService } from '../../services';
+```
+
+---
+
+# 7. Signal Standards
+
+Default State Management:
+
+```typescript
+readonly loading =
+  signal(false);
+
+readonly employees =
+  signal<Employee[]>([]);
+```
+
+Derived State:
+
+```typescript
+readonly activeEmployees =
+  computed(() =>
+    this.employees()
+      .filter(x => x.active)
+  );
+```
+
+Avoid:
+
+```typescript
+BehaviorSubject
+```
+
+for component state.
+
+---
+
+# 8. Template Standards
+
+Use Angular Control Flow.
+
+Preferred:
+
+```html
+@if (loading()) {
+  <app-loader />
+}
+```
+
+Avoid:
+
+```html
+<div *ngIf="loading()"></div>
+```
+
+---
+
+## Loops
+
+Always track:
+
+```html
+@for (
+  employee of employees();
+  track employee.id
+)
+```
+
+Never omit track.
+
+---
+
+# 9. HTML Standards
+
+## Accessibility
+
+Every interactive element must have:
+
+* aria-label
+* keyboard support
+* visible focus state
+
+Example:
+
+```html
+<button
+  aria-label="Submit Timesheet">
+</button>
+```
+
+---
+
+# 10. SCSS Standards
+
+## Structure
+
+```scss
+:host {}
+
+.component {}
+
+.component__header {}
+
+.component__body {}
+
+.component--active {}
+```
+
+Use BEM.
+
+---
+
+## Forbidden
+
+```scss
+!important
+```
+
+Unless overriding third-party code.
+
+---
+
+# 11. SOLID Principles
+
+## Single Responsibility
+
+One component.
+
+One purpose.
+
+---
+
+## Open Closed
+
+Extend behavior.
+
+Avoid modifying stable code.
+
+---
+
+## Dependency Inversion
+
+Depend on abstractions.
+
+Not concrete implementations.
+
+---
+
+# 12. Error Handling Standards
+
+Every async operation must handle:
+
+* Loading
+* Success
+* Error
+
+Example:
+
+```typescript
+try {
+  ...
+}
+catch (error) {
+  ...
+}
+finally {
+  ...
+}
+```
+
+---
+
+## User Messages
+
+Never show raw API errors.
+
+Bad:
+
+```typescript
+error.message
+```
+
+Good:
+
+```typescript
+'Unable to load employees.'
+```
+
+---
+
+# 13. Logging Standards
+
+Use:
+
+```typescript
+LoggerService
+```
+
+Never:
+
+```typescript
+console.log()
+```
+
+Production code must not contain:
+
+```typescript
+console.log
+console.warn
+console.debug
+```
+
+---
+
+# 14. Security Standards
+
+Never:
+
+```typescript
+innerHTML = value
+```
+
+Never:
+
+```typescript
+bypassSecurityTrustHtml()
+```
+
+without approval.
+
+---
+
+## Secrets
+
+Never commit:
+
+* Tokens
+* Passwords
+* API Keys
+
+Use environment configuration.
+
+---
+
+# 15. Performance Standards
+
+Mandatory:
+
+* OnPush
+* Lazy Loading
+* Signals
+* track in loops
+
+Use:
+
+```typescript
+computed()
+```
+
+instead of recalculating data.
+
+---
+
+## Avoid
+
+```typescript
+get employees() {
+}
+```
+
+in templates.
+
+Prefer signals.
+
+---
+
+# 16. Testing Standards
+
+Minimum Coverage
+
+```text
+80%
+```
+
+Critical Logic
+
+```text
+95%
+```
+
+Required:
+
+* Services
+* Guards
+* Interceptors
+* Pipes
+* Complex Components
+
+---
+
+# 17. Documentation Standards
+
+Document:
+
+* Public APIs
+* Shared Components
+* Complex Business Rules
+
+Example:
+
+```typescript
+/**
+ * Calculates overtime based on
+ * company attendance policy.
+ */
+```
+
+---
+
+# 18. TODO Standards
+
+Required Format:
+
+```typescript
+// TODO(HRMS-123):
+// Replace mock service
+```
+
+Never:
+
+```typescript
+// TODO later
+```
+
+---
+
+# 19. Git Standards
+
+Branch Names:
+
+```text
+feature/timesheet-preview
+bugfix/leave-balance
+hotfix/auth-redirect
+```
+
+---
+
+## Commit Format
+
+```text
+feat(timesheet): add preview panel
+
+fix(attendance): correct clock-out validation
+
+refactor(shared): simplify data table
+
+test(payroll): add salary service tests
+```
+
+---
+
+# 20. AI Generated Code Standards
+
+AI-generated code must:
+
+✓ Use Standalone Components
+
+✓ Use Signals
+
+✓ Use inject()
+
+✓ Include Error Handling
+
+✓ Include Loading States
+
+✓ Include Accessibility
+
+✓ Include Types
+
+✓ Follow Naming Standards
+
+Reject code that:
+
+✗ Uses any
+
+✗ Uses NgModules
+
+✗ Uses constructor injection
+
+✗ Uses default change detection
+
+✗ Contains console.log
+
+✗ Contains hardcoded values
+
+---
+
+# 21. Code Review Checklist
+
+Before Approval:
+
+□ Strict typing
+
+□ No any types
+
+□ OnPush enabled
+
+□ Signals used correctly
+
+□ No memory leaks
+
+□ Tests added
+
+□ Accessibility verified
+
+□ Responsive design verified
+
+□ Security reviewed
+
+□ Performance reviewed
+
+□ Documentation updated
+
+---
+
+# 22. Definition of Code Quality
+
+Code is considered production ready when:
+
+✓ Readable
+
+✓ Typed
+
+✓ Tested
+
+✓ Accessible
+
+✓ Secure
+
+✓ Performant
+
+✓ Maintainable
+
+✓ Reviewed
+
+✓ Documented
+
+✓ Follows architecture standards