OWASP / OWASP/Nest

[DOCS] Standardize docstrings and add usage examples in apps/common/utils.py

Open
#3,971 5 comments 0 reactions 1 assignee Claimed by @Angelmendiratta View on GitHub
enhancement
Dominant language
Python
Stars
451
Forks
707
Avg merge
22h 59m
Merged PRs (30d)
91

Description

### Description
While exploring the `backend/apps/common/utils.py` file, I noticed that several core utility functions (such as `round_down`, `natural_number`, and the case converters) provide brief descriptions but lack usage examples and detailed argument context.

To improve the Developer Experience (DX) for new contributors and align the codebase with the **Google Python Style Guide**, I propose updating the documentation for these utilities.

### Proposed Changes
I will refactor the docstrings in `backend/apps/common/utils.py` to include:
1. **Standardized Google-style formatting** for Args and Returns.
2. **Doctest-style Examples** (`>>>`) to provide immediate clarity on function behavior.
3. **Enhanced descriptions** for complex logic like `validate_url` and `natural_date`.

### Impact
This change will make the utility layer self-documenting and easier to maintain without adding any overhead to the runtime logic.

### Requirement
I would like to work on this issue. Please assign it to me!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.