Is a sudden occurence of an unbearable desire to write some comments, a symptom of a bad design? [closed]

It's difficult to tell what is being asked here. This question is ambiguous,开发者_运维百科 vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center. Closed 12 years ago.

Imagine... You have written some code; implemented some interfaces, used some design patterns, passed many unit tests, extracted many methods for sake of refactoring and so. You developed, developed, developed... But at some mysterious point, for some reason you, something inside you started to whisper you that you should write a comment now. Something pokes you that if you don't write a comment something will be missing or something can be not exactly clear...

Then you comment your code! :(

Can this be a secret sign of a bad design?

If you find yourself in a situation that if you don't comment your code at that spiritual(!) moment, it won't have its mission completed; can we consider it as a reliable symptom of a possible bad design in your code?

---

If you're feeling like you should add comments because something is missing (documentation for clients perhaps!), then it may not be an indication that your code itself is bad. If you're adding comments because something is unclear, you need to decide whether it's unclear because the code is hard or because the underlying domain is hard. If it's the code, you need to rewrite it to make it clearer. If it's the domain that's making it difficult, feel free to comment it extensively for people who aren't as familiar with the domain in question, and leave the code alone.

---

While I agree that the code should be as self documenting as possible, this is not always enough. There is only so much you can do without writing comment. A good example is, as one of my mentor said : "Code can only document what you do, not what you dont do".

Even if you have the best possible design, there will always be places where you will need comments to make your intentions clear.

Comments can be usefull to document a tricky technical problem. If a problem is complex, its implementation will be complex and will need documenting.

Comments are also usefull to document business rules. Those rules will be expressed into code, but the code will rarely explain the reasons behind the rules. Comments will make things clearer ...

---

Sometimes writing comments is easier than cleanup your code to make it clear enough the understand what it does and why. I usually do the later, but comments can be the best approach at times. esp. if you generate javadocs.

---

I tend to do this when I've already tried several other approaches which didn't work, in an effort to stop myself coming back in a few months, and trying to refactor back to those approaches again.

---

I put this as an asnwer because I think it's important. Basically I agree with Stuart:

A coding standard at a previous job said to only ever comment code if it is dealing with something exceptionally computationally difficult such as a complex compression or encryption algorithm. That company had the best damn code I have EVER seen and I have worked in a wide range of different types of company.

---

As much as I agree with everyone who is arguing for self documenting code, there is one place I feel they overlooked where comments are important: Interfaces, and to a lesser extent, abstract methods. The contract on an Interface method is usually (and probably should be) more complicated than can be described in the method name. The only way you can document that is with a comment.

---

If code falls into standard patterns with sensible method names etc then it's often not necessary to comment. However, often I'll write a quite short routine that does something nifty, usually involving a good dollop of maths and a bit of swishy logic. I'll usually comment every line of something like this, as if I don't I'll come back to it later and look at it and think 'Why is it doing that?' whereas if I've commented it it's so so much easier. It saves me a minute or more of re-thinking the problem every time I look at it.

So to answer the question, No, not necessarily.

---

Dittos to Guillaume. I strongly disagree with those who say that if you just write your code clearly enough, comments are unnecessary.

Yes, it is surely true that some types of comments are unnecessary if you just use meaningful variable and function names. Like, why write:

x17=bbq*rg; // Multiply price by tax rate to get tax amount

Better to write:

taxAmount=price*taxRate;

And I just find it mind-bogglingly annoying when someone writes a comment that just restates what any competent programmer should be able to instantly tell by reading the code. I don't know how many times I've seen useless comments like:

x=x+1; // Add one to x

Like, wow, thanks for telling me what "+" does. Without the comment I might have had to Google it.

But there are at least three types of comments that I find very useful:

1. Comments that explain the overall purpose or approach behind some large block of code. Something that gives me a clue why you're doing what you're doing. Like, "// When the delivery location is changed, recalculate the sales tax using the rates applicable to the new location". Sure, I could hack through the code and ultimately figuring out what you're doing, but if you tell me up front, I don't have to figure it out. This isn't supposed to be a game where we see how long it takes me to solve the problem. Just tell me the answer.

2. Comments that exlain how a function should be called or how to use an API in general. Like, "To retrieve the pricing data, first call contactPricingServer to make the connection, then call getPrice for each item you need a price for, and finally call closeConnection to release the resources." Maybe if I studied all the available functions long enough I could figure that out, but again, this isn't supposed to be a quiz. Just tell me the answer.

3. Probably the most valuable of all: Comments that explain a piece of code that might not be obvious. Like, "We must look up by sale date and customer number rather than by sale id because the sale id's on the recon server aren't updated until month end." I've had plenty of times that I've looked at some code that looked strange and wondered if it was a bug or if there is some good reason why the programmer did it that way. The problem is not that I cannot figure out what the program is doing. The problem is why it is doing X rather than doing Y, when Y seems like what it ought to do.

Update

I have to laugh. Right after making the above post, including the remark about useless comments that just restate what the programmer can instantly see from looking at the code, I went back to doing some real work, and the next piece of code I looked at said:

// Set the sales status to "S" and the delivery date to today.
setSalesStatus("S");
setDeliveryDate(today);

Like, wow, thanks for that helpful comment. That cleared up all my confusion immediately. Because, you see, the REAL question that I'm trying to figure out is, Why are we setting a delivery date here? This doesn't appear to be an appropriate place to be doing that. But instead of a comment that explains the purpose of the code, all I have is a restatement of the obvious. Arggh.

---

Personally, I always comment my code. No long lines, but short bits like

// parser starts here
...
// mail!

etc.

However, if you have a 5 line script, commenting might be a bit overkill... especially if your filename says it.

If it's for you, and you alone, you totally should do it if you feel like it. If you're working on something with a team, I'd do it always. Just to notify the others what they're looking at.

---

Comments and bad design are two different things. Comments help to understand certain things in a bigger context. Comments (and documentation in general) help new folks in a project to do some reading on their own.

Actually we have some unwritten rule that we must comment our stuff. If I wonder whether or not somebody can understand this at first glance it's already a sign of a required comment.

However, it's not a sign of bad design.