While programming learning, I guess, you often read the sentence that you have to add comments, if you don't comment, your code is bad. It's truth, but only half-truth. Let me allow to share with my experience.
Until 2 years ago, I was trying add comments everywhere. The below comments were obviously for me.
class PostsController
{
/**
* Deletes the post
* @param int $id
* @return mixed
*/
public function delete(int $id) {
$this->checkAccess();
Post::find(($id)->delete();
return response()->json([]);
}
/**
* Checks if the user has access to the posts
* @return void
*/
private function checkAccess() {
$user = Auth::user();
if(!$user || !$user->hasAccess('posts')) {
abort(403);
}
}
}
Today, I don't think so. Someone could ask - why? In my opinion, these methods aren't complex, so they are easy to read. Moreover, names of methods are enough expressive. I always try to describe in a name what this method does. Of course, it isn't easy, and I sometimes make mistakes - especially because English isn't my native language, but good names are the key. To be honest, how often do you read descriptions of functions? I guess, you mainly do it when a name isn't enough clear.
When do comments make sense?
For some cases, comments are really powerful. At work, I add comments to describe a part of a code which might not be clear for another developer. Please have a look on below example:
const sendComment = (type, id, body, files) => {
const formData = new FormData()
for (let i = 0; i < files.length; i++) {
formData.append(`files[${i}]`, files[i])
}
// Content-Type has to be undefined because a browser needs to add "boundary" automatically
// See: https://developer.mozilla.org/en-US/docs/Web/API/FormData/Using_FormData_Objects#sending_files_using_a_formdata_object
return api.send(`/comments/resource/${type}/${id}`, formData, {
'Content-Type': undefined,
})
}
In some app, I use fetch API
to send data via API. Regarding on the documentation, you can't set Content-Type
header if you want to send files. Here, I added the comment to explain it for another dev. This code could be weird for someone else who doesn't know about it. The comment is really helpful there.
Another case, where I use comments, is a situation when the business logic isn't obvious, and explaining of it might be useful when you need to be back to your code after some time.
class Post extends Model {
public function isVisible(User $user = null):bool {
// admins can see all posts in the frontend
if($user && $user->isAdmin()) {
return true;
}
return $this->active;
}
}
If I need to be back to the code after weeks, I'll see why I decided to return true
for admins. For more complex logic, a comment would be more powerful.
In the past, I would do something like that:
public function isVisible(User $user = null):bool {
// if the user is an admin, return true
if($user && $user->isAdmin()) {
return true;
}
return $this->active;
}
Now I see, it doesn't make sense because you can analyse the code to know what the code do, more important is why the code does it in that way.
Summary
Comments might seem to be a trivial thing but they aren't. You need some experience to do it in a good way. I hope the sharing how I do it at the moment will help you. You can share how you do it in the comments.