## 🚀 View Commenting Convention for Fast Debugging & Navigation

To streamline debugging and code navigation, every view class should be preceded by a **clearly structured comment block**. This format makes it easy to:

* Quickly locate views by endpoint path or method
* Search views by type (`APIView`, `ViewSet`) via CLI tools like `rg` or `grep`
* Immediately understand what a view is responsible for

---

### ✅ Format

```python
###################################################################################
# @<view-type>  |  <METHODS IN UPPERCASE> - <endpoint path>
###################################################################################
```

#### Example:

```python
###################################################################################
# @api-view  |  POST, GET - /me/companies
###################################################################################
class MeCompanyApiView(GenericAPIView):
    ...
```

---

### 🔎 Field Reference

| Field             | Purpose                                                             | Example                        |
| ----------------- | ------------------------------------------------------------------- | ------------------------------ |
| `@<view-type>`    | Declares the kind of view used — aids CLI-based filtering/searching | `@api-view`, `@view-set`       |
| `<METHODS>`       | HTTP methods the view handles                                       | `GET`, `POST`, `PUT`, etc.     |
| `<endpoint path>` | The URL route where the view is mounted                             | `/users/files/<int:pk>/upload` |

---

### 📘 View Types

Use one of the following view-type identifiers:

| Type        | Description                                                        |
| ----------- | ------------------------------------------------------------------ |
| `@api-view` | For views that inherit from `GenericAPIView` or `APIView`          |
| `@view-set` | For views that inherit from `GenericViewSet`, `ModelViewSet`, etc. |

---

### ♻️ HTTP Methods

List only the HTTP methods the view explicitly supports:

* `GET`
* `POST`
* `PUT`
* `PATCH`
* `DELETE`
* `OPTIONS`

Order doesn't matter, but use **uppercase** for consistency.

---

### 📍 Endpoint Path

This should reflect the actual route where the view is registered.

Use Django/DRF-style parameters:

```text
/users/<uuid:pk>/folders/
/files/<int:file_id>/download/
/me/companies/
```

---

### 🚧 Best Practices

* Use this comment format **before every `GenericAPIView`, `ViewSet`, or similar**.
* Avoid including permissions, descriptions, or extra metadata unless necessary.
* Keep comments strictly scoped to navigation/debugging.
* Use CLI tools to search:

  ```bash
  rg "@api-view"
  rg "companies"
  rg "POST, GET"
  ```

---

This pattern ensures developers can **lightning-fast locate views**, trace bugs, and maintain high code readability in large DRF codebases.