Having worked in a couple of multinational software companies as well as startups, I feel I have seen or at least heard about almost every type of software comment there is, I will try to list them, and I am happy for you to reach out to me if there is a type you feel I have missed.
In computer programming, a comment is a programmer-readable explanation or annotation in the source code of a computer program. They are added to make the source code easier for humans to understand and are generally ignored by compilers and interpreters that is how they can be written in free-form text, They can be written in any language.
These are the worst type of comments you can find in a source code repository. They normally exist because some developer was testing out a couple of ideas, one of them finally worked so the developer just checked in the modified files without removing the commented-out code. They can also exist because someone needed to remove a piece of logic and thought it would be a good idea to leave it commented in case they needed it back in the future. (Hey Fellows, THIS IS WHY WE HAVE VERSIONING SYSTEMS).
If it's commented out, then it may rot: when you suddenly decide that you need it again, you realize that it no longer compiles, or needs to be rewritten to make it fit with other things that have changed in the meantime. Commented-out code also adds useless clutter to the source files and makes them confusing to read.
These types of comments you have already seen whether you are working for a large company or making use of open source components. These types of legal comments will have copy and usage rights. these types of comments are required when you are working for a large organization. The open source community uses them heavily too sometimes to limit commercial use or usage of open source components in closed source software Example from GNU #NoticeInSourceFile
Example :
Documentation comments are intended for anyone likely to consume your source code, but not likely to read through all of it it. If you are building a library or framework that other developers will use, you need some form of API documentation. The documentation comments can be used to generate readable standalone auto-generated documentation documents. Also Integrated Development Environments (IDEs) can parse these Doc comments to provide guidance and hints to developers while writing software.
For example, Javadoc is a document generator tool in Java programming language for generating standard documentation in HTML format. It generates API documentation. It parses the declarations ad documentation in a set of source files describing classes, methods, constructors, and fields.
Example Documentation Comments:
public class Test {
}
and
public int methodName (...) {
}
Clarification comments are intended for anyone (including you in the future) who may need to revisit a piece of code to either refactor or extend your code. Almost always, a clarification comment is a code smell. It tells you that your code is too complex. You should remove clarification comments and simplify the code instead
“good code is self-documenting.”
Example of a bad comment
$str = str_replace(array("\{","\}")," ",$str);
Rather than decorating a confusing statement, you could have spent the time making the code itself more readable Maybe a function named, remove_curly_braces called from another function named sanitize_input?
There are also times when you see a redundant comment. If the code is already simple and obvious, there’s no need to add a comment.
p_ids = [p.id for p in all_products]
There are still times when no matter what you do to the code itself, a clarification comment is still warranted. This usually happens when you need to add some context to a non-intuitive solution.
Example :
static struct page *__dma_alloc(struct device *dev, size_t size,
dma_addr_t *handle, gfp_t gfp)
{
struct page *page, *free, *end;
int order;
gfp &= ~(__GFP_COMP);
These are comments that provide information to parties that may not be familiar with something with a specific business use case
Example
pattern = re.compile('^(\+2[- ]?)?0\d{10}$')
Any member of the team can simply read the expression without understanding it if they are not familiar with regex.
Most programmers put TODO comments in their code to track problems they see and ideas they have. Programmers use TODO comments because they’re convenient and allow you to stay in the code, reducing distractions.
Example:
7. Warning of consequences
Example
def test_loading_a_massive_file():
....
These types of comments are a warning to fellow developers of the consequences. Without these types of warnings, if a program/test suite runs slowly, your fellow developer might waste his/her time finding the problem.
There are times when — after a lot of effort — it turns out that the seemingly naive solution to a problem is the best. In those scenarios it is almost guaranteed that some other coder will come around thinking they are much smarter than you are and start messing with the code, only to discover that your way was the best all along. Sometimes even that other coder is your future self.
In those cases, it’s best to save everyone the time and embarrassment and leave a comment.
Examples from SO Question : What is the best comment in source code you have ever encountered :
// Magic. Do not touch.
The above examples are more about being funny than being helpful. You SHOULD leave a comment warning others not to pursue some seemingly obvious “better solution,” if you’ve already tried and rejected it. When you do, the comment should specify what solution you tried and why you decided against it.
Please let me know if you think there are other types of comments that I missed, I am happy to discuss them.
![Information Security Series: [Part2] Principles of Privileges](/_next/image?url=https%3A%2F%2Fcdn.hashnode.com%2Fres%2Fhashnode%2Fimage%2Fupload%2Fv1647290198557%2FdaFz7fDND.png&w=3840&q=75)
![Information Security Series: [Part1] Principles of Security](/_next/image?url=https%3A%2F%2Fcdn.hashnode.com%2Fres%2Fhashnode%2Fimage%2Fupload%2Fv1647209120646%2FxVK4QYmwq.png&w=3840&q=75)