I just recently started documenting my code as it helped me. Though I feel like my documentations are a bit too verbose and probably unneeded on obvious parts of my code.
So I started commenting above a few lines of code and explain it in a short sentence what I do or why I do that, then leave a space under it for the next line so it is easier to read.
What do you think about this?
Edit: real code example from one of my projects:
async def discord_login_callback(request: HttpRequest) -> HttpResponseRedirect:
async def exchange_oauth2_code(code: str) -> str | None:
data = {
'grant_type': 'authorization_code',
'code': code,
'redirect_uri': OAUTH2_REDIRECT_URI
}
headers = {
'Content-Type': 'application/x-www-form-urlencoded'
}
async with httpx.AsyncClient() as client:
# get user's access and refresh tokens
response = await client.post(f"{BASE_API_URI}/oauth2/token", data=data, headers=headers, auth=(CLIENT_ID, CLIENT_SECRET))
if response.status_code == 200:
access_token, refresh_token = response.json()["access_token"], response.json()["refresh_token"]
# get user data via discord's api
user_data = await client.get(f"{BASE_API_URI}/users/@me", headers={"Authorization": f"Bearer {access_token}"})
user_data = user_data.json()
user_data.update({"access_token": access_token, "refresh_token": refresh_token}) # add tokens to user_data
return user_data, None
else:
# if any error occurs, return error context
context = generate_error_dictionary("An error occurred while trying to get user's access and refresh tokens", f"Response Status: {response.status_code}\nError: {response.content}")
return None, context
code = request.GET.get("code")
user, context = await exchange_oauth2_code(code)
# login if user's discord user data is returned
if user:
discord_user = await aauthenticate(request, user=user)
await alogin(request, user=discord_user, backend="index.auth.DiscordAuthenticationBackend")
return redirect("index")
else:
return render(request, "index/errorPage.html", context)
I like to do two kinds of comments:
There is no need to explain what every line of code is doing, coders can read the code itself for that. Instead focus on what part of the overall task a certain chunk of code is handling.