While it may be true that the best code is self-documenting, even the clearest written source code requires adequate documentation in order to be quickly parsed and understood by human readers.
In practice, though, where and how much to comment is much more up to the individual developer to decide than elements of the code itself. The compiler or interpreter doesn't generally care about your comments; after all, they're not for it, they're for us humans. And so while some organizations and projects will offer guidelines, commenting styles are much more open to interpretation.
In general, being clear and concise with your comments will be appreciated. But particular within open source, you don't have the luxury of assuming that other developers looking at your code are familiar with the context in which it was written. Everyone is new to the project at some point, and you can't count on them understanding the project's history, its quirks, or the libraries it uses. New contributors may not be native speakers of your language, either.
And so well-written and well-placed comments are an important part of your project's documentation. Are you making sure that your project's code is as accessible as it can be?
How often do you comment? Do you think you comment frequently enough? Let us know what you think!
9 Comments