Cursor rule

1---
2description: Code style and naming conventions for UGTLive
3globs: ["**/*.cs"]
4alwaysApply: true
5---
6 
7# Code Style and Conventions
8 
9## Naming Conventions
10 
11### Classes and Methods
12- **Classes**: PascalCase (e.g., `ConfigManager`, `TranslationService`)
13- **Public Methods**: PascalCase (e.g., `GetValue()`, `TranslateAsync()`)
14- **Private Methods**: camelCase (e.g., `loadConfig()`, `processImage()`)
15- **Private Fields**: Underscore prefix + camelCase (e.g., `_instance`, `_configValues`)
16- **Constants**: UPPER_SNAKE_CASE (e.g., `GEMINI_API_KEY`, `TRANSLATION_SERVICE`)
17 
18### Properties
19- Use PascalCase for public properties
20- Prefer explicit getters/setters over auto-properties when logic is needed
21- Pattern: `GetVariableName()` / `SetVariableName()` for ConfigManager
22- Direct property access for simple UI bindings
23 
24## Code Layout
25 
26### Indentation and Braces
27- **Indentation**: 4 spaces (no tabs)
28- **Braces**: Allman style (opening brace on new line)
29- **Line Length**: Prefer < 120 characters, wrap if needed
30 
31### Using Statements
32- System namespaces first
33- Third-party namespaces second
34- Application namespaces last
35- Group related usings together
36 
37### Example Structure
38```csharp
39using System;
40using System.Collections.Generic;
41using System.IO;
42using System.Threading.Tasks;
43using System.Windows;
44using UGTLive;
45 
46namespace UGTLive
47{
48    public class ExampleClass
49    {
50        private static ExampleClass? _instance;
51        private readonly Dictionary<string, string> _configValues;
52 
53        public static ExampleClass Instance
54        {
55            get
56            {
57                if (_instance == null)
58                {
59                    _instance = new ExampleClass();
60                }
61                return _instance;
62            }
63        }
64 
65        private ExampleClass()
66        {
67            _configValues = new Dictionary<string, string>();
68        }
69 
70        public string GetValue(string key)
71        {
72            return _configValues.TryGetValue(key, out var value) ? value : "";
73        }
74    }
75}
76```
77 
78## Singleton Pattern
79 
80### Implementation
81- Use lazy initialization with null check
82- Private constructor
83- Static Instance property
84- Thread-safe initialization (simple null check is sufficient for this app)
85 
86```csharp
87private static ConfigManager? _instance;
88 
89public static ConfigManager Instance
90{
91    get
92    {
93        if (_instance == null)
94        {
95            _instance = new ConfigManager();
96        }
97        return _instance;
98    }
99}
100 
101private ConfigManager()
102{
103    // Initialization
104}
105```
106 
107## Error Handling
108 
109### General Principles
110- **Avoid try/catch blocks** unless absolutely necessary
111- **Check for null** before using objects
112- **Log errors** using `LogManager.Instance.LogError()`
113- **Console.WriteLine** for debug output
114- **MessageBox.Show** for user-facing errors (on UI thread)
115 
116### Error Handling Pattern
117```csharp
118// Prefer null checks over try/catch
119if (response == null)
120{
121    Console.WriteLine("Response is null");
122    return null;
123}
124 
125// Log errors
126LogManager.Instance.LogError("Error description", exception);
127 
128// User-facing errors on UI thread
129Application.Current.Dispatcher.Invoke(() =>
130{
131    MessageBox.Show($"Error: {message}", "Error Title", 
132        MessageBoxButton.OK, MessageBoxImage.Error);
133});
134```
135 
136## Comments
137 
138### When to Comment
139- Complex algorithms or business logic
140- Non-obvious code decisions
141- API integration details
142- TODO items for future improvements
143 
144### Comment Style
145- Use `//` for single-line comments
146- Use `///` for XML documentation on public APIs
147- Keep comments concise and up-to-date
148 
149## File Organization
150 
151### File Structure
1521. Using statements
1532. Namespace declaration
1543. Class declaration
1554. Private fields
1565. Public properties
1576. Constructor
1587. Public methods
1598. Private methods
160 
161### One Class Per File
162- Each class should be in its own file
163- File name matches class name
164- Exception: Small helper classes can be in same file
165 
166## Nullable Reference Types
167 
168### Null Handling
169- Use nullable reference types (`string?`, `object?`)
170- Check for null before dereferencing
171- Use null-coalescing operator (`??`) when appropriate
172- Use null-conditional operator (`?.`) for safe access
173 
174```csharp
175private string? _optionalValue;
176 
177public string GetValue()
178{
179    return _optionalValue ?? "default";
180}
181 
182if (_optionalValue != null)
183{
184    // Use _optionalValue safely
185}
186```
187 
188## Constants
189 
190### Configuration Keys
191- Define as `public const string` in ConfigManager
192- Use descriptive UPPER_SNAKE_CASE names
193- Group related constants together
194 
195```csharp
196public const string GEMINI_API_KEY = "gemini_api_key";
197public const string GEMINI_MODEL = "gemini_model";
198```
199 
200## Async/Await Patterns
201 
202### Method Naming
203- Async methods end with `Async` suffix
204- Return `Task` or `Task<T>`
205- Use `await` for async calls
206 
207```csharp
208public async Task<string> TranslateAsync(string text)
209{
210    var result = await httpClient.GetStringAsync(url);
211    return result;
212}
213```
214 
215## LINQ Usage
216 
217### When to Use LINQ
218- Prefer LINQ for collection operations
219- Use method syntax for complex queries
220- Keep queries readable
221 
222```csharp
223var filtered = items.Where(x => x.IsValid)
224                    .OrderBy(x => x.Name)
225                    .ToList();
226```
227 
228## String Handling
229 
230### String Operations
231- Use `string.IsNullOrWhiteSpace()` for null/empty checks
232- Prefer string interpolation (`$"text {variable}"`) over concatenation
233- Use `StringBuilder` for multiple concatenations
234 
235```csharp
236if (string.IsNullOrWhiteSpace(value))
237{
238    return defaultValue;
239}
240 
241var message = $"Processing {count} items";
242```
243