Coding Conventions

[hinogi]

I struggle a lot reading the current code because of some intrinsic coding conventions or lack thereof. Would it possible to get something instated that gives some guidelines on how to write things?

Some examples:

• Reveal intent — name should say what it holds/does without needing a comment (elapsed_time_in_days, not d)
• No disinformation — name should match the actual type/behavior (don't call a dict a _list)
• Meaningful distinctions — if two vars differ, the name should say why (raw_data vs normalized_data, not data vs data2)
• Pronounceable & searchable — avoid cryptic abbreviations and magic numbers; use MAX_RETRIES, not 5
• No mental mapping — avoid i, x, tmp outside tiny local scopes
• Nouns for classes, verbs for methods — Customer, not DataManager; save(), not data()
• One word per concept — pick fetch or get, not both, across the codebase
• No puns — don't reuse the same word for different meanings
• Use domain vocabulary — match terms your team already uses in conversation
• Scale length to scope — short names OK in tiny loops, descriptive names for anything wider-reaching
• PEP 8 basics — snake_case vars/functions, PascalCase classes, UPPER_SNAKE_CASE constants, booleans as predicates (is_valid, has_permission)