From 549d419b69b69f3351939f1fc360810f23a26307 Mon Sep 17 00:00:00 2001
From: Lorenz Hilpert <l.hilpert@paragon-data.de>
Date: Fri, 28 Mar 2025 20:03:29 +0100
Subject: [PATCH] docs: update TypeScript and Angular guidelines for improved
 best practices and error handling

---
 docs/guidelines.md | 114 +++++++++++++++++++--------------------------
 1 file changed, 47 insertions(+), 67 deletions(-)

diff --git a/docs/guidelines.md b/docs/guidelines.md
index 99557629e..fd49586b7 100644
--- a/docs/guidelines.md
+++ b/docs/guidelines.md
@@ -106,19 +106,24 @@ export class FeatureComponent {
 
 ## Code Style
 
-### TypeScript Guidelines
+## TypeScript Guidelines
 
-- Use strict mode in all TypeScript files
-- Explicit return types on public methods
-- No `any` types - use proper typing
-- Use type inference when obvious
+- Use strict mode in all TypeScript files.
+- Explicit return types on public methods.
+- Avoid using `any` types; use proper typing.
+- Use type inference when the type is obvious.
 
 ### Angular Guidelines
 
-- Use standalone components
-- Implement OnPush change detection
-- Use Signals over Observables when possible
-- Follow Angular naming conventions
+- Implement OnPush change detection for better performance.
+- Prefer Signals over Observables for component-level state.
+- Follow Angular naming conventions for files, classes, and selectors.
+- Use `inject()` instead of `constructor()` for Dependency Injection (DI).
+- Use Angular's new template control flow syntax @if() @for() @switch() @defer() etc...
+- Use `trackBy` functions with `ngFor` loops to optimize rendering performance.
+- Enable `strictTemplates` in Angular configurations for better type safety.
+- Implement reusable error boundaries for consistent error handling.
+- Use strongly typed error objects for better debugging and maintainability.
 
 ### Import Organization
 
@@ -137,32 +142,35 @@ import { MyService } from './my.service';
 
 ### Unit Testing Requirements
 
-- Test files should end with `.spec.ts`
-- Use Jest as the test runner
-- Follow AAA pattern (Arrange-Act-Assert)
-- Mock external dependencies
+- Test files should end with `.spec.ts`.
+- Use Spectator for Component, Directive and Service tests.
+- Use Jest as the test runner.
+- Follow the Arrange-Act-Assert (AAA) pattern in tests.
+- Mock external dependencies to isolate the unit under test.
 
 ### Example Test Structure
 
 ```typescript
+import { createComponentFactory, Spectator } from '@ngneat/spectator/jest';
+import { MyComponent } from './my-component.component';
+
 describe('MyComponent', () => {
-  let component: MyComponent;
-  let fixture: ComponentFixture<MyComponent>;
+  let spectator: Spectator<MyComponent>;
+  const createComponent = createComponentFactory(MyComponent);
 
-  beforeEach(async () => {
-    await TestBed.configureTestingModule({
-      imports: [MyComponent],
-    }).compileComponents();
-
-    fixture = TestBed.createComponent(MyComponent);
-    component = fixture.componentInstance;
+  beforeEach(() => {
+    spectator = createComponent();
   });
 
   it('should create', () => {
-    expect(component).toBeTruthy();
+    expect(spectator.component).toBeTruthy();
   });
 
-  // Additional test cases...
+  it('should handle action correctly', () => {
+    spectator.setInput('inputProp', 'testValue');
+    spectator.click('button');
+    expect(spectator.component.outputProp).toBe('expectedValue');
+  });
 });
 ```
 
@@ -180,49 +188,35 @@ describe('MyComponent', () => {
 - Follow feature-based store organization
 - Implement proper error handling
 
+## Error Handling
+
+- Create reusable error boundaries for consistent error handling.
+- Use strongly typed error objects to improve debugging and maintainability.
+
 ## Performance
 
 ### Best Practices
 
-- Lazy load features
-- Use trackBy with ngFor
-- Implement proper change detection
-- Optimize images and assets
-- Use pure pipes instead of methods in templates
+- Use lazy loading for features and modules.
+- Use pure pipes instead of methods in templates.
+- Optimize images and assets.
+- Monitor and minimize bundle sizes.
+- Use `trackBy` functions in `ngFor` loops to improve rendering performance.
 
 ### Memory Management
 
-- Unsubscribe from observables
-- Use destroy$ pattern or DestroyRef
-- Clean up event listeners
-- Monitor bundle sizes
+- Unsubscribe from observables to avoid memory leaks.
+- Use the `destroy$` pattern or `DestroyRef` for cleanup.
+- Remove event listeners when components are destroyed.
+- Monitor bundle sizes.
 
 ## Common Commands
 
-### Development
-
-```bash
-# Serve application
-npx nx serve isa-app
-
-# Generate library
-npx nx g @nx/angular:library my-lib
-
-# Run tests
-npx nx test my-lib
-
-# Lint
-npx nx lint my-lib
-
-# Build
-npx nx build isa-app
-```
-
 ### Git Workflow
 
 ```bash
 # Create feature branch
-git checkout -b feature/my-feature
+git flow feature start my-feature
 
 # Commit changes
 git commit -m "feat: add new feature"
@@ -233,23 +227,9 @@ git push origin feature/my-feature
 
 ## Documentation
 
-### Component Documentation
-
-```typescript
-/**
- * @description Component description
- * @example
- * <isa-my-component
- *   [input]="value"
- *   (output)="handleOutput($event)">
- * </isa-my-component>
- */
-```
-
 ### README Requirements
 
 - Component usage examples
-- Installation instructions
 - Configuration options
 - Dependencies
 - Common issues and solutions