From 9fb9a817bf30057e3e4df19397aedbf280e7ca37 Mon Sep 17 00:00:00 2001
From: Abu Jabar Mubarak <139158216+abujabarmubarak@users.noreply.github.com>
Date: Sat, 12 Jul 2025 19:34:57 +0530
Subject: [PATCH] Create code_guidelines.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

### Summary

This PR addresses Issue #33851 by adding a new consolidated documentation file named `code_guidelines.md` under `doc/source/development/`. The purpose is to unify the various coding style and contribution guidelines that were previously scattered across multiple locations such as:

- `code_style.html`
- `contributing.html#code-standards`

### Why This Change?

Many new contributors struggle to find a complete set of code formatting rules. Some style guidelines are embedded in scripts, others in separate docs. This unified document:

- Reduces guesswork for contributors
- Minimizes repetitive code review comments
- Increases visibility and onboarding efficiency

### What's Included

✅ A new file `code_guidelines.md` that includes:
- Formatting with `black`, `flake8`, and `isort`
- Import ordering conventions
- Usage of f-strings, type checking, and `None` comparisons
- Function and variable naming rules
- Docstring formatting using `numpydoc`
- Testing standards using `pytest`
- Git commit and PR hygiene
- Reference links to official tools and standards

### Follow-up Actions

- [ ] Optionally link this in `index.rst` under `doc/source/development/` for visibility in the sidebar
- [ ] Receive feedback from maintainers for refinement or integration with existing content

---

Let me know if any refinements or reorganization are needed. Happy to make the changes based on your feedback.
---
 doc/source/development/code_guidelines.md | 175 ++++++++++++++++++++++
 1 file changed, 175 insertions(+)
 create mode 100644 doc/source/development/code_guidelines.md

diff --git a/doc/source/development/code_guidelines.md b/doc/source/development/code_guidelines.md
new file mode 100644
index 0000000000000..007c720db0732
--- /dev/null
+++ b/doc/source/development/code_guidelines.md
@@ -0,0 +1,175 @@
+
+# Pandas Code Guidelines
+
+This document consolidates all coding style and contribution guidelines for Pandas developers into one place. Please follow these rules to ensure clean, consistent, and maintainable code.
+
+---
+
+## ✍️ Code Formatting
+
+### 🔹 Use `black`
+- Pandas uses [Black](https://black.readthedocs.io/en/stable/) to automatically format code.
+- Run `black` before committing:
+  ```bash
+  black pandas/
+  ```
+
+### 🔹 Line Length
+- Limit lines to **88 characters** (as per Black).
+- For docstrings or comments, use **80 characters** when possible.
+
+---
+
+## 🚫 Linting & Static Checks
+
+### 🔹 Use `flake8`
+- Run `flake8` to check for style violations:
+  ```bash
+  flake8 pandas/
+  ```
+
+### 🔹 Use `isort` for import sorting
+- Keeps imports grouped and ordered.
+- Run:
+  ```bash
+  isort pandas/
+  ```
+
+---
+
+## 📦 Imports
+
+- Standard library imports first
+- Third-party packages next (e.g., `numpy`, `pytest`)
+- Local pandas imports last
+
+**Example:**
+```python
+import os
+import numpy as np
+from pandas.core.frame import DataFrame
+```
+
+---
+
+## 🔤 Strings
+
+- Use **f-strings** for formatting:
+  ```python
+  name = "Abu"
+  print(f"Hello, {name}")
+  ```
+
+- Prefer `repr()` over `str()` for debugging.
+- Avoid unnecessary whitespace inside `{}`:
+  ```python
+  f"{x}"  ✅
+  f"{ x }"  ❌
+  ```
+
+---
+
+## 🧪 Testing Guidelines
+
+- Use `pytest` framework.
+- Test files should be placed in `pandas/tests`.
+- Use fixtures instead of setup/teardown methods.
+- Mark known failures:
+  ```python
+  @pytest.mark.xfail(reason="Issue #12345")
+  def test_example():
+      ...
+  ```
+
+- Run all tests with:
+  ```bash
+  pytest pandas/
+  ```
+
+---
+
+## 👨‍🔧 General Python Style
+
+- Follow [PEP8](https://pep8.org/)
+- Avoid `type(x) == y` — prefer `isinstance(x, y)`
+- Use `is` for `None` comparison:
+  ```python
+  if x is None:
+      ...
+  ```
+
+- Avoid importing inside functions unless necessary.
+- Avoid `import *`
+
+---
+
+## 🧠 Function/Variable Naming
+
+| Type         | Style        | Example         |
+|--------------|--------------|-----------------|
+| Function     | `snake_case` | `compute_mean()`|
+| Variable     | `snake_case` | `total_count`   |
+| Class        | `PascalCase` | `DataFrame`     |
+| Constant     | `UPPER_CASE` | `MAX_ROWS`      |
+
+---
+
+## 📝 Docstrings
+
+- Use [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) format.
+- Include:
+  - Short summary
+  - Parameters
+  - Returns
+  - Examples
+
+**Example:**
+```python
+def compute_mean(data):
+    '''
+    Compute the mean of a list.
+
+    Parameters
+    ----------
+    data : list of float
+        The input data.
+
+    Returns
+    -------
+    float
+        Mean of the input.
+    '''
+```
+
+---
+
+## 🔁 Pre-commit Hook
+
+- Pandas uses `pre-commit` to automate linting and formatting:
+  ```bash
+  pip install pre-commit
+  pre-commit install
+  ```
+
+---
+
+## 💡 Git & Pull Request Guidelines
+
+- Use meaningful commit messages.
+- Format: `DOC: Add new section to code guidelines (#issue-number)`
+- PRs should be small and focused.
+- Always reference the issue being addressed.
+
+---
+
+## 📚 Reference
+
+- [Pandas Contribution Guide](https://pandas.pydata.org/docs/development/contributing.html)
+- [Pandas Code Style](https://pandas.pydata.org/docs/development/code_style.html)
+- [PEP8](https://pep8.org/)
+- [Black](https://black.readthedocs.io/en/stable/)
+- [pytest](https://docs.pytest.org/en/stable/)
+
+---
+
+*This file was created to unify the code formatting and contribution expectations for new and experienced developers working on Pandas. Following these guidelines will help ensure high-quality and maintainable code.*