trustme/docs/COMMENTS.md

🚀 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

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

Example:

###################################################################################
# @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:

/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:

  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.