Commenting code is the worst practice promoted by "wannabe smart" books about software engineering. Joshua Block in his How to Design a Good API and Why it Matters keynote notes that code should read like prose and shows the good example:
And I completely agree with this statement. Thus good code is self-explanatory and does not require comments. On the other hand comments will never rescue bad code. Sure, we can use something like "TODO: I will fix this dummy trick in the next iteration", but no more than it.
10 comments:
I think if every app was as simple as if speeding, throw alert, you're right comments wouldn't be needed, but most apps aren't.
Elegance is a matter of perspective. Having an existing body of domain knowledge removes the need for comments, because the business logic in the 'prose' makes sense. A programmer coming into a 50k line application, might like a few notes along with the prose to, if nothing else explain the relationships, and importance of certain things.
No comments == bad to me. Too many comments also == bad, there's a balance that I think the good programmers get.
Think of it this way, even prose, has footnotes.
I agree with john. Just because something is clear prose to developer A, doesn't mean it's not riddles and tongue twisters to developer B.
Like everything, comment in moderation :) Little outlines are often very welcome.
I think commenting isn't evil. I don't know if you know AS2api (AS2) or ASDoc (AS3), they use comments as input for generating documentation. Take a look at this page (LiveDocs) for the best commenting guide. I think every class should have ASDoc comments, It's also helpful for most external actionscript editors (not from Flash IDE) with nice completion (Eclipse, FlashDevelop)
Alright, I get your point; it is useless to comment this way:
// counter increases by 1
counter ++;
I agree with the footnotes example. And those footnotes are used only in case if something is really so unclear so it must be explained. Quite rarely to be honest.
Large classes and large methods are the most popular code smells. So if you reduce them in your system, each class and each method would be self-explanatory enough without comments.
Sure, when you develop API or framework to be reused by thousands or millions, comments are obligatory at least because you can generate documentation using tools like ASDoc and thus minimize the number of requests for support. But when it comes to some narrow scope solutions, I believe, it is much better to invest the time into the code quality rather then comments. :-)
Totally agree. A lot of comments show me the weakness of the team. If guys are strong there is no need to use ugly dumb comments.
Yes, when you start learning to code, you read all the books that say "comment, comment, comment". Then you get a little more experience and you embrace the "all code should be self documenting" school of thought. Eventually, you'll get through that phase too, and come down to earth and know when to comment and when to not.
If all you are ever doing is projects that will only be worked on by yourself and you won't have to look at them again after you're done, or as easy as your example, then sure -- don't comment.
But I comment where its needed because when I pick up that app 6 or 12 months down the line, I want to remember how and why I used that 3rd party engine or that obscure hack to get around some Flex oddball issue. I also use comments when I know I'm going to be working with teams or clients that may not share the same level of expertise as myself.
Personally, commenting is so easy, don't affect the execution of the end product, and can only help, so why not use it?
Balance is da thing.
Yeah there should be a happy medium where only necessary comments are written. Sometimes I'll write comments to get myself through a bit of logic:
// First get the target child
// Now cast it to its blah blah...
I find it keeps me focused. When I'm done, I usually erase the comments.
It should be against the LAW not to comment. Team leads should be able to force some kind of compiler setting that if it doesn't see an adequate comment to code ratio that it won't compile.
Ya, I agree. Code should read like it's telling a story. If Variable and Function names can only go so far.
The one thing it won't capture are *WHY* certain decisions are made. This is where comments are so important.
Developers are notorious for lack of documentation, and many open source projects are examples of that. You definitely don't want to take away what bit of documentation you can at least expect out of them.
Comments should be in such plain English that an MIS analyst could read through the code and understand what it's doing.
Post a Comment