python-guidelines

# Python Guidelines **Integrate into existing code. Don't append to it.** > Simple is better than complex. Flat is better than nested. > Errors should never pass silently. Unless explicitly silenced. > If the implementation is hard to explain, it's a bad idea. > > -- The Zen of Python (PEP 20) ## Code Philosophy - Match existing naming, importing, and signature patterns. Use existing utilities and data structures. - Functions have a single purpose. Don't hardcode behavior that makes them less general. - No trivial wrappers for 2 lines or less. Inline it. - Inline single-use variables at the usage site. - No try/except unless critical. Let errors surface. - No duplicate code. - Functions handle their own input validation. No if-else checks in main. - Use pathlib, not os.path. - Consider API and time costs for MongoDB/Gemini/OpenAI/Claude/Voyage. Don't do this: ```python # Generate comment report only if requested if include_comments: comment_report = generate_comments_report(start_date, end_date, team, verbose) else: comment_report = "" print(" Skipping comment analysis (disabled)") ``` Do this: ```python comment_report = generate_comments_report(start_date, end_date, team, verbose) if include_comments else "" ``` Ask yourself: "Am I adding code, or integrating into what exists?" ## Simplicity Over Abstraction **YAGNI: You Aren't Gonna Need It.** Don't build for hypothetical future requirements. Add complexity only when the current task demands it. A...