Incidentally, I am not a big fan of comments. I think they are often an artifact of using weak languages. I think that programming languages should be a good enough way to express programs that you don't have to scrawl additional clarifications on your source code. It would be a bad sign, don't you think, if a novelist had to print notes in the margins saying "she left without saying anything because she was angry about the trampled petunias?" It is the job of the novel to make that clear. I think this is what SICP means when they say "programs must be written for people to read, and only incidentally for machines to execute." I use comments mostly to apologize/warn about hacks, kludges, limitations, etc.
This is in the context of PG defending his claim Succinctness is Power for a programming language. Love him or hate him, you cannot ignore him. I think he is a true thoughtleader in the programming languages community ..
3 comments:
The code can be very good at conveying the solution. I personally feel that we should use comments to convey the problem, and sometimes to document the assumptions that it makes.
Like Paul Graham, I almost never comment my code.
But there are constructions that are notoriously difficult to read regardless of how expressive the language itself is. One such example is regular expressions. They might need a clarifying comment, but you could also accomplish that by encapsulating the expression within a method, with a descriptive name.
I think comments should explain business logic behind the code, not the code logic itself.
Say, if we do some checks and actions, one may need to explain why: this can be a defect fix, or some other design decision.
Or, we have created some class serving as a proxy for some another object. If this class serves as a part of some access pattern, not directly related to business logic, this should be explained somehow, to save the time of developers on "visualizing" the design in their heads via studying everything "aarh! this is the main class, those are just helpers...".
Pure code is just a bit higher than machine instructions. Unless we program in business-level DSL, we have to explain the logic using comments.
So don't look for excuses, the good code should have comments. But these comments should not repeat what code does, but why it does so and not something else.
Post a Comment