98 lines
3.0 KiB
Markdown
98 lines
3.0 KiB
Markdown
## 🚀 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.
|
|
Write `ALL` instead of counting one by one, if your endpoint handles
|
|
all of the supported methods.
|
|
---
|
|
|
|
### 📍 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.
|