Clean code shouldn’t have too many comments, or should be “self-documenting” as your manager might say. I even heard that some believe that all comments are bad. I call BS on this one: slapping a single label on things and calling it a day is just lazy. What sort of comments would you keep in your source?

#programming #tech #softwaredevelopment

So we all heard it: comments bad, clean code good. But which comments are actually bad? Well, redundant comments that for example: just repeat function names. Comments that become misleading because someone forgot to update them. Comments that are mandated, like writing javadoc on every function, even the simplest getters. Also: avoid journal comments that note what has been done to this file. Use git commit messages for that.
So which comments are actually useful?
Informative comments that allow to provide context that is inaccessible otherwise: like an example of formatted date, or a string that fits a regex. Just glancing at these will tell you exactly what is happening.
There are other comments that are useful, but for a reason that doesn’t immediately come to mind: legal reasons. In order to comply with certain laws, corporate standards or to provide critical information - these have to be in your code. Accept them as they come.
Next, let’s take a swing at something that isn’t really easy to convey in code: intent. As programmers we strive to solve problems in the best possible way. Sometimes - we’ll need to add information why we do something, not only how.
Clarification comments are helpful to explain things you cannot easily rename or refactor. These will for example translate names from one domain to another, or just provide a label that is easier on the eyes of coders.
Warning of consequences - these are really good things to know when reading the code. You might find that putting information that something isn’t thread safe, or takes a long time to run is actually very beneficial to your mental health. Believe me - learning these things on your own can really be a massive headache.
TODO and FIXME comments - some projects use them very heavily. I recommend putting them in your source code. TODO comments should be accompanied by ticket ID and can be checked in your repository, so you can find specific places in code later. FIXME are a bit different - these should be viewed as temporary comments that you add while working on code, but before commiting. They’re there so you remember to fix some things before sending a change to the repository.
And lastly: amplification comments. Sometimes the exact reason why something is really important isn’t very visible through code. Think of very obscure conditions that happen very rarely, yet are still occuring in your program. Your safeguards can get lost if another programmer comes across such code and decides to “optimize it”. Putting an amplification comment will help them see things your way. [example 5]

And lastly, the most important comments are the ones you leave under this video! Let me know what you think, subscribe, and I’ll see you in the next one, cheers!