When I am writing small scripts for myself, I stack my code high with comments (sometimes I comment more than I code). A lot of people I talk to say that I should be documenting these scripts, even though they are personal, so that if I ever do sell them, I would be ready. But aren't comments a form of documentation?
Wouldn't this:
$foo = "bar"; # this is a comment
print $foo; # this prints "bar"
be considered documentation, especially if a developer is using my code? Or is documentation considered to be outside of the code itself?
Best Answer
Comments are definitely documentation. For most projects, comments are (unfortunately) the primary (if not only) form of project documentation. For this reason, it's very important to get it right. You need to make sure that this documentation stays accurate despite code changes. This is a common problem with comments. Developers often "tune" them out when they're working in familiar code, so they forget to update comments to reflect code. This can create out-of-date, and misleading comments.
A lot of people suggest making the code self-documenting. This means that instead of comments, you restructure your code to remove the need for them. This can get rid of most of the "what" and "how" comments, but doesn't really help with the "why" comments. While this might work effectively to get rid of most comments, there are still plenty of times where writing a comment is the simplest and most efficient way to document a piece of code.