-: Now as you saw, many comments are bad,
but actually there also are acceptable
or good comments out there.
For example, one kind of comment you will see
in some code files would be legal information.
Again, this example code file from before
which contains many bad comments
it also does have such a legal disclaimer
or such a legal comment right at the top.
And depending on the kind of project you're working on
you might be required to add something like this
to every code file you write.
Of course if it's your own project,
you can decide this on your own
if you need that or not.
But in a lot of organizations, you might be required
to add something like this.
And then of course, it's absolutely fine to do so.
I mean, you don't really have an alternative
to that anyways.
It doesn't really hurt to code readability though
because it sits right at the top of the file.
It's clear that it contains legal information and therefore
for it can easily be skipped and ignored.
Now, another kind of comment, which is actually good
is a comment that adds an explanation
which can't be delivered or replaced by proper naming.
And this would be an example.
We're using a regular expression
and even though that's a relatively simple one,
regular expressions can get quite long
and having a little comment next to it
which simply explains what does regular
expression does or checks for,
can be worth a lot.
Another kind of comments which could make sense
would be a comment that warns you of something.
For example, here we have a comment warning us
that this specific API,
the local storage API is only available in Java Script,
running in the browser, not running
on the number of machine with node JS for example.
Now we can always argue whether we really need this comment.
I mean after all, you could expect fellow developers
to be aware of that,
or you might want to place it in a try catch block
or some if statement anyways,
but if you have neither of that for some good reason
then adding a warning like that could make sense.
Now last but not least a comment
which has also okay to have would be a to do note.
You see one here even though that file
had a lot of bad comments
this is not one of the bad comments.
This to do note can make sense.
Now, of course we could argue
whether we should have an empty method
where everything is missing
and if it wouldn't be better to just remove it
and then add it all in one go.
But if you do have some code which is unfinished,
adding a note like this can indeed make sense
and can be okay.
Of course you shouldn't overdo it though.
And instead you should focus on writing code
which you finish instead of leaving unfinished code
sitting around in your code base.
Now one last kind of comment
which can make sense is a comment
where you add documentation
especially when providing a public API.
So methods, properties, classes, which can be used
by other people, not just in your organization
but maybe also from all around the world.
If you are building a library
which you wanna share as a third party library
with other people, then adding documentation strings
which can be picked up by IDEs
for example, of course also makes sense.
And here it then really comes
down to the programming language you're using.
For example, for Python, you have a certain structure
for how such documentation strings should like
and other programming languages
might bring their own conventions.
So documentation comments are a special kind of comment,
which can make sense depending
on which kind of project you are working on.
And that is already at for hate comments.
Hence the general rule really
is that you should avoid comments
with the few exceptions I showed you over the last minutes.