This is yet another attempt to reconcile various attitudes towards code comments. See also MethodCommenting,ToNeedComments, WellCommentedCode, WellFactoredCode, CommentingChallenge, StripExcessiveComments, TreatCommentsWithSuspicion, the various ExtremeProgramming pages, etc. I want to list the costs and benefits which comments have in a relatively neutral way, without actually coming out and saying whether comments are a good thing. What I'm seeking here is some model of what comments' strengths and weaknesses are, what their role should be, when they should be supplanted by other tools. ''Later...'' I find I can't do that without some notion of what the alternatives are, so I'll start with a list: ''This is a comment intended to draw attention to the fact that this page consists entirely of comments about whether or not comments should be used to help explain code, and to request that some code be added to help explain these comments. -FoodmiralAckBar'' '''Alternatives to comments''' * Embed the information from comments into variable, method and class names. Refactor the code until this can be done. IdentifiersAreComments. * ProjectLore: leave the information in the minds of the programmers. * ??? : leave the information in a dusty 3-ring binder or other separate files. * Use tools to extract the information from the source, e.g.: * Source-code browsers. * UnitTest''''''s. * Use assertions (ReplaceCommentWithAssertion, AssertionsAsComments). * Use literate programming: that is, put your code in your documentation instead of documentation in code. See http://www.literateprogramming.com. Many of the pro arguments are really arguments in favor of documentation rather than arguments in favor of a specific methodology of associating code and documentation. Please add others, or other examples. Meanwhile, the main show... ---- '''Costs''' * '''They take time to write.''' In fact, good comments are very hard to write. You need to think carefully both about what you are doing, and also about who your audience is and what they will already know. This is time-consuming. ''Programming is time-consuming. I find (and this may be a purely personal idiosyncrasy) that I write the comment first. By the time I've expressed what I'm going to do in English prose, spitting it out in code is trivial. This means that the comment captures my thought process in designing the code, alternatives considered and discarded (and why), and many other things that are not expressed in code. For me, doing it this way allows me to capture useful information from the design process that would otherwise be discarded. -- JimPerry'' * '''They take time for the machine to read.''' Yes, I worked with a guy who advocated no comments because it slowed down the assembler. Of course, this was in the days of 8" SSSD floppy disks, but I thought it was a bit over-the-top at the time. He was the same guy who persuaded me to build him a breadboard circuit without the board. The components were wired together as a blob in mid-air - a 3D layout. It worked; he played with it for a day and then threw it away. Sometimes his minimalism was right on target. * '''They take up screen real estate'''. This is especially true for some verbose styles - for example where every comment has blank lines which make it at least 3 lines long. It's a problem because the comments push the real code off the screen, which means you must exercise your short-term memory more when trying to understand it. [Of course, a silly coding standard that mandates horrendous block comments like this isn't a good reason to not use comments. Better to change the standard.] ''I worked at a company where all functions had big block-style comments at the top. A lot of the modules were state machines with a bunch of small action routines for state transitions. If it weren't for the comments, you could easily fit the entire modules within a couple pages of screen space. For state machines, it's important to quickly scan the code to understand the overall flow of the system. The comments made this cumbersome. I never got any values from the comments; they simply repeated things that were obvious from the code, and they often became inaccurate. -- SteveHowell'' * '''They are less reliable than the code itself.''' Comments can get out of sync with the code if people change the code without updating the comments. Then anyone reading the comments will be mislead. Even if they are in sync, you can never be sure of that, so you have to read the code itself to make sure anyway. [This is far often more true of offline documentation than of in-line comments; with comments that are inline it is easier to enforce IfYouChangeTheCodeChangeTheComment.] ''Hang on here. Just because comments can get out of date doesn't mean that comments are bad - it just means that you have to write GOOD comments. The argument that comments can go out of date so you shouldn't write comments is similar to the argument that because executable code can crash the machine it's run on you shouldn't write executable code! -- MattCline'' [Actually, it just means that you have to maintain your comments whenever you maintain your code. It adds cost. And there's no way to test a comment for correctness by executing it. Comments communicate only to people. If you can accomplish that communcation through the code, without the comment, there are lots of reasons to do so (this page is full of them)] "A mismatch between code and comments is valuable information that tells you that work needs to be done in that area. If code is always accompanied with a comment, then each form of expression acts as a kind of logical checksum for the other, thereby improving the reliability of software in the same way that double-entry accounting improves the reliability of bookkeeping. But there is a more general reason for having both comments and code: software has a dual nature - it runs on the CPU and in the human mind, and each of these processors has a different nature. Code is adapted to CPUs and comments are better understood by humans. From a philosophical perspective, code is more deterministic, and comments are more goal-directed. In other words, code tends to be expressed in terms of efficient causation, whereas comments tend towards final causation and purposeful explanation. The identity of each processor implies the type of expression that is appropriate for each. -- TimLee" ''About four years ago I worked for a company where the engineering manager banned comments, despite most of the engineers being strongly in favour of commenting code (seriously!). The manager's arguments was "the comments might be wrong, so they aren't worth the risk". I took his flawed axiom and used some simple logic. Well, we might get the code wrong, so we should stop coding too. And I might go into the wrong office tomorrow morning, so I'll stay in bed all day instead. I quit soon afterwards. -- Jim McCluskey'' * '''Adding comments can be 'high risk':''' I've spent hours tracking down a bug because I trusted a comment that someone other than the original author added after the fact. The code was complex, so I trusted the comment -- my mistake, but I would hesitate to call all comments 'low-risk'. ''I spent an hour tracking down a bug because I trusted a method name. -- JohnFarrell'' * '''They encourage bad code.''' The idea here is that people will write bad code and then comment it, rather than write good code. ''Has anyone ever observed this? Frankly I've encountered very few programmers willing to write comments, and none who prefer commenting to writing good code. -- JimPerry'' ''I have observed this. Bad code tends to grow comments because it is hard to understand and people become afraid to change it. Many programmers will comment bad code rather than repair it. -- WayneMack'' ''I have observed this too. (Similar forces are at work when user documentation grows to compensate for poor interface design. Programmers are reluctant to change the interface). -- JamesCrook'' ''I have also seen this. When I see code with great big boilerplate headers for every method I think "Uh oh". A lot of the time the code inside is either written the way the programmer hoped it would work (as described in the method header), or it's written with as few characters as possible as if the explanation in the method header excused them from writing legible code. And then there are the comments written to describe the clever trick that makes the code work. Those are a sure give away that the code is rotten (see KillYourDarlings). -- Phil Goodwin'' * '''They are less precise than code.''' ''It's very difficult to write "plain English" as unambiguously as code. This is because it isn't limited, etc. Put another way: comments lie. -- RonJeffries'' ''The reduced precision of comments is their strongest point. Reduced precision can mean greater abstraction, and abstraction is one of the programmer's best friends. Comments can express things at a higher level than the code, AND they can illustrate WHY code is doing something, not just WHAT it's doing. -- MattCline'' * '''Programmers ignore them.''' Since comments are frequently out of date, experienced programmers ignore them as a reflex. ''(This is based on my experience with mentoring a programmer for a week on some code I wrote. Despite my repeated reminders, he always skipped right past the comments and to the code. I don't know if this is true overall. -- JimLittle)'' ** If the code they comment is not reasonably obvious, then a comment can save a lot of time ("Oh, that's what all this goofy stuff is doing!"). * '''They give a false sense of security'''. If my code is littered with comments, it must be: * Working. * Understandable, even if it's not necessarily working. * Easy to debug, even if it's not really understandable. * Maintainable, even if... (You get the idea) : I have observed this more than once. -- RobHarwood ''This isn't an argument against comments; it is only an argument against drawing these false conclusions from comments. -- DavidSarahHopwood'' [If some of the conclusions that we are likely to draw from a comment are false ones, I would rather not have that comment at all. ''Then you're an idiot. All of the inferences given above are invalid; they are the fault of incompetent thinkers, not of the comments.'' Comments are appropriate to communicate high-level concerns to people. But they often get used to communicate things that would be better communicated through clear, well-factored code. ''That some comments are bad or misused tells us nothing about comments, and is particularly irrelevant to the point here.''] * '''They reduce the clarity of well-expressed code'''. Well-factored code with good names is clearer and easier to read than the same code with comments. The comments end up being redundant. At this point, they should be removed. (Note that this implies that if comments add to clarity, the code is poorly expressed and could use refactoring.) Is that it? I'm tempted to add, "They say nothing which the code itself doesn't say", but that's only a drawback because of the other factors. ''If comments say nothing that code doesn't say, then the comments are poorly written. Many of these so-called disadvantages to comments are, in fact, symptoms of *bad* comments! But just because comments can go bad doesn't mean they're bad by nature. -- MattCline'' ---- '''Benefits''' * '''Plain English is easier to read than code.''' This is because it isn't limited to the rather simple and rigid abilities of computer parsers. English (or any natural language) is more expressive than any programming language. ''English is more ''descriptive'' than any programming language. It doesn't express programs.'' * '''Comments can be more precise than code.''' They can include mathematical/logical notions like "for-all", "there-exists" and so forth. Routine pre- and post-conditions are sometimes easier to express as comments than as executable assertions. '' Do you mean "precise" or "concise" here? Because comments are (ideally) at a higher level of abstraction than code, they should be able to express things more concisely, but not necessarily more precisely... -- MattCline'' Yes, both. I can say "This function finds an approximation to n!". The function itself might return results that are a bit off. ''Unfortunately few systems support mixing SpecificationLanguage constructs with executable code, but that would arguably be a better approach than using comments for this.'' * '''Comments ease comprehension by collecting information into one place.''' For example, by explaining the context in which a routine will be called. * '''Comments can be at a higher level of abstraction than the code they document.''' When this is true, the comments act as a specification for the code. (You could delete the code itself, and later reproduce it from just the comments.) This can make them easier to understand. AssemblyLanguage programmers sometimes use C language to comment their code. * '''Comments can describe things that cannot otherwise be clearly expressed in the source language.''' At a higher level than the "C commenting Assembly", how do you express that "This code licensed under the LGPL", "Jane Doe requested this feature", or "see "Rate Monotonic Scheduling" article by David B. Stewart and Michael Barr in _Embedded Systems Programming_ 2002-03 for a proof that this algorithm is optimal" in any ProgrammingLanguage outside of comments? * '''Comments are shorter than the code they document.''' This means you can scan code quicker by just reading the comments until you get to the bit you are interested in. ''Although it is not always the case that a comment is shorter than the code it documents.'' * '''Comments factor out explanations.''' One alternative to comments is longer class, method and variable names. But these names are used far more often, so you actually waste screen real estate (i.e. short-term memory) overall. A comment can explain the meaning once, clearly and fully, and then the variable name (or whatever) only has to remind you. ''Combining this with '''They take up screen real estate''' in the costs section, shouldn't the synthesis be to not waste real estate for the combined total of code and comments? -- DavidSarahHopwood'' * '''Comments are persistent.''' This is in contrast to ProjectLore, information kept in the minds of your programmers. Lore is liable to be lost when those programmers resign or get run over by a bus [TruckNumberFixed]. * '''Comments are accessible.''' You can discover information from comments very easily, eg without having to interrupt someone else. They are right there in the code where they're needed. (This is another anti-ProjectLore and anti-"separate files" point.) ''But see the remarks in ToNeedComments. The code itself can do a large part of this. Where it can, aren't the comments redundant? -- RonJeffries'' Could you expand on that? ToNeedComments is pretty big. Most of the points above are of the form "comments are more XXX than code" so it seems peculiar on the face of it to say the code can do the same. -- JimPerry * Requested Expansion. Comments are accessible: code can be accessible too. Comments are persistent: code is even more persistent and tracks changes automatically. Comments factor out explanations: well-written code factors out explanations and improves quality at the same time. Comments are shorter than the code they document: this is unproven at best. Comments can be more precise than code: this seems to me to be false; code is precise, natural language isn't. -- RonJeffries * Code is precise about WHAT is happening; (good) comments are precise about the WHY. Simple example (assuming a C programming environment): if you have a pointer as function argument, you don't know if this is so because the pointed-to object will be modified, or if there are performance considerations behind this. A more expressive programming language can say more about the WHY, but there will always be something you can't express in a programming language (unless you work with a HalNineThousand). -- FreddyTheCat ''[Re: "[if] a pointed-to object will be modified", in C, use const; I hate this use of comments. It's less powerful than proper use of const. -- SunirShah]'' ''[const is good but still insufficient; it doesn't help to differentiate between output-only and update (input-output) parameters]'' * I have espouse that same philosopy for over 20 years. Here is a usenet post to comp.lang.c from 1993: http://groups-beta.google.com/group/comp.lang.c/browse_frm/thread/1434361fd50433a2/e0c8d25cee708ea0?lnk=st&q=code+what+why+author:Uri+author:Guttman&rnum=1&hl=en#e0c8d25cee708ea0 -- Uri Guttman * '''Comments discipline the mind.''' Writing a comment is a way of testing your ability to explain the code. ''If code is difficult to explain to another person, that's a sign it should be rewritten. And then throw away the comment and keep the rewritten code. Comment the rewritten code to add information the code itself doesn't provide. -- RonJeffries'' ''That makes the assumption that the "other person" has the same education, experience or knowledge as the person that wrote the code. This is not always the case. Also, just because the code has been refactored and/or rewritten, that does not automatically mean that it will clear or intuitive to ''everyone'' that reads it. Comments serve as a (more or less) "plain English" way of explaining code or what the code is '''trying''' to do (which may be more important than what the code is '''actually''' doing). My experience has shown this to be of value when less-experienced staff ends up reading or doing maintainence work on code; they may learn what the code is doing by reading the comments. While it is a valid argument that comments easily get out-of-date, as already mentioned; this is a fault with the developer(s), not the comments (or the ''act of'' commenting) itself.'' -- JamesTwine * '''Comments are easier to skim-read than code.''' When you're looking through a program, you look briefly at a lot of stuff you don't bother to read properly, by way of orientation. If the stuff is commented well, you can look at the comments instead of the code, saving time and thus making your reading more fluent. -- GarethMcCaughan * '''Comments don't affect execution speed.''' (I just tossed this one in - rarely a factor in practice.) ''It is important. When execution speed is important, and you've just written some 'clever code' (for 'clever' read 'incomprehensible') to achieve speed, it would be very sad indeed if comments were costly....'' * '''Comments are low-risk changes.''' Comments are highly unlikely to change the operation of the software, even when the code is misunderstood and the comments are wrong. I have seen some rare instances where an unterminated comment has broken working code and it is a real pain to find, but then again this is very rare. * '''Comments can document rejected code.''' This is hinted at above, in the "comments take time to write" paragraphs. A comment can discuss the design decisions made in coming to write the code that's actually there. So if the 'obvious' solution has been rejected as incorrect (because it's too slow, or causes conflicts with some other subsystem), the reason for the actual implementation can be documented in the comments. BlindAlley. * '''Comments document the intent of the code.''' This can clarify the purpose of tricky code (but refactoring the code would be better). Also, if a change is made to the code so that the code no longer executes the intent, then having a redundant comment will allow the programmer to restore the code (but having automated UnitTest''''''s would be better). Ok - I don't feel I'm doing so well here. The points are not so orthogonal or clear. I'll leave it at that and hope someone else can improve or rewrite it. ''You're doing brilliantly. Keep up the good work!''. * '''Comments document unexpected complexity.''' I'm sure we've all seen a function with a misleading name, which takes a strange set of parameters, or returns some bizarre value on success (and that can't be changed). A good comment next to the function call explaining that the call is indeed correct can save a lot of developer time if a coder sees this code and is tempted to "fix" it. Ditto with certain language features that can produce code that ''looks'' wrong. ---- I especially like "Comments discipline the mind". Teaching tests your understanding of a subject. Comments as tutorial can demonstrate your understanding of the goal, regardless of whether you successfully implemented it. -- WayneCarson ''A lot of these benefits are at best intangible. In particular, my customers expect me to discipline my mind on my own time. On their clock they are looking for high-quality, maintainable functionality at a predictable cost they can afford. -- RonJeffries'' The idea here is that writing a comment is similar to running a UnitTest. It's a way of checking the quality of a particular piece of code, rather than a form of training for the programmer. -- DaveHarris [Bogus analogy. A UnitTest is can be executed automatically to tell you if your code works or not. All you've proved by writing a lengthy comment about something is that you understood it well enough to write a lengthy comment about it--that says nothing about the quality of the accompanying code. Some people seem to rely too much on comments precisely because they AREN'T good at producing quality code. There are legitimate reasons to use them, but comments are often a CodeSmell.] ''How do we connect some of these goods back to the point of the development? -- RonJeffries'' Good question. I definitely want to come onto that. Writing that list emphasized (to me) some of the roles of comments that would be better taken on by other tools. For example, perhaps the "explaining the code" role is better done by CodeReview(s) or by turning to the colleague at the desk next to you and actually explaining it to them. That said, I do want to distinguish between the ideal working environment, where all necessary tools are available, and the actual environments that some of us are stuck with. -- DaveHarris ---- Can anyone report on a project where the length of the method names was actually a problem? -- RonJeffries It's always a problem once they get over 20 or 30 characters long. The code just gets too unwieldy. No expression will fit on a single line. -- DaveHarris In embedded systems it matters a lot, as it limits the amount of code you can debug. ''Not so for embedded systems that use cross-compilers and remote debugging - which most do.'' I have run into linker errors involving the length of method names. Although each programmer had a reasonable 20-character name, when they all were concatenated due to pointers to functions taking overloaded class methods with classes as arguments, we easily get to 300-character symbol names which the current Microsoft linker cannot handle (as of 2004). Where does this madness stop?!? This example is from the C++ STL (Standard Template Library)! -- GreggTracton I also see problems with variable names that vary by only a few characters or by the order of the words in the name. Comments are a good way to point out these slippery slopes. -- GreggTracton ''Better names would be more helpful, in my opinion.'' To answer Ron, a number of (poor) embedded C compilers / linkers only use the first 32 or so characters in global identifiers. Also, to reduce the possibility of name clashes, many shops have the convention of putting the defining module name in each global identifier, reducing the useful size to about 20 to 25 chars. Now, the length of method/function names really becomes an issue. ---- On the redundancy of comments... My experience is that it takes longer to figure out something from the code than it does to read a comment. My loaded language reflects that -- reading code is "figuring out" while reading comments is "reading." At the very basic word level, I find an English sentence with spaces easier to read than a V''''''eryLongBumpyCase''''''Method''''''Name''''''Like''''''This. When you have 4 or 7 lines full of expressions involving such names, where each expression typically doesn't fit on a single line, and where each piece does such a small part of the job that you have to keep many of them in your mind at once to grok the big picture of what is really going on - then the difference is magnified. If there ''is'' such a difference in readability, how big can we allow it to grow? If it takes, say 5 seconds to understand an English comment and 45 seconds to figure out some code, is that enough to justify the comment's presence, or is it still redundant? If not 5/45, what ratio would justify the comment? Are the 5/45 numbers plausible - does anyone have any empirical measurements? -- DaveHarris When I need to change the code, I find it gets done faster if I ignore the comments and read the code. That way I avoid errors, and understand what actually is going on. I agree that it seems easier to read comments than code, but it's more productive to read code than comments. -- EricUlevik When you're concentrating on a particular bit of code, you need to read that code, not just the comments attached to it. But when you're concentrating on one bit of code and need to understand another, you don't always need the very precise understanding that reading its code would give you. Skimming the comments can be much better. -- GarethMcCaughan ---- '''when code and comments disagree, the comments are always wrong -- or are they?''' One of the most time consuming problems is when the code and the comments differ. I have spent a lot of time investigating things only to find the comments were incorrect. This often diverts time from finding the actual problem I am interested in. -- WayneMack The problem with comments is, of course, that in a disagreement with the code they are ''always'' incorrect; tautologically so. (See the "less reliable than the code" heading above.) Actually, I'm not so sure. I believe it ''is'' possible for the comments to be 'correct' while the code is 'incorrect'. Of course it depends on whether you use the word 'correct' to mean 'how things actually behave' or 'how things are supposed to behave (to work properly)'. For example, if there is a customer requirement, and an exact quote of what the customer said is embedded in the comments. If there is a bug and the software doesn't do that, the comment is correct, the code is incorrect. For another example, if I read a comment that says "this method must be synchronized", and the code isn't synchronized, then something's wrong here, but it MIGHT be the code that's wrong not the comment. ''One would like to know why it needs to be synchronized. Duh, yes, multiple threads, but what are the threads and what is the assumed access pattern? Very important in understanding a system.'' If you can't figure out what the assumed access pattern is, just by reading the code, I'm certainly not going to tell you. ---- On some of the projects I've worked, System Engineers write requirements for the Software Developers to implement. Comments aid in demonstrating that the Software Developer understands the requirements. This is sort of covered by several of the above benefits -- WayneCarson ---- One area where I still find comments helpful is in documenting WorkAround''''''s for third-party code that does not work as expected. For example, a function call that simply does not work and needs to be replaced with a more convoluted work around. The comment serves as a "bad smell," but one that cannot be currently resolved. -- WayneMack ''I'd like to add an enthusiastic second to this one... Any time I have to do something Genuinely Strange to work around a problem, I aspire to always explain the whys and wherefores. I also try to include some debug code that will test to ensure that the workaround is still needed (though this doesn't happen as often as I'd like).'' ''On the other hand, I have yet to be burned by a misleading comment. Once bitten and all that.'' ''-- Mark Storer'' ---- ''Moved from ToNeedComments'' ''I've had the luxury of having written good software with teams with a strong comment focus, and with a team whose focus is to write code so simple and so clear as to need few comments. In my actual experience, the latter works better. Communication and code quality really are enhanced by this practice, not degraded.'' ''I didn't believe it going in; I tried it; I learned something.'' -- RonJeffries But even in the very simple CommentExample, the code was not clear, because it didn't answer common questions a developer would have. This is imho the primary role of comments. -- AnonymousDonor I actually use such practices, and have for years. I also use comments. I don't know what's left to try, aside from writing the same code and leaving out the comments, but I know that when I do that '''I''' find it to be less informative and to require more effort to maintain. The options are not '''just''' "poorly-decomposed code with comments to make up for it" and "well-decomposed code without comments"; I prefer "well-decomposed code '''with''' comments". "Don't comment bad code -- rewrite it" is a very old programmer's maxim. I still find, when reading code I consider well commented, that I skip the code and just read the comments. -- DaveHarris Even in following such admirable patterns there is still benefit to well-crafted natural-language expression of what code is doing. CommentCostsAndBenefits touches well on some of the reasons why. Is anyone saying that you shouldn't document your code at all? Perhaps not in so many words, but deprecating language about comments and insinuations that comments are used largely to salvage poorly-written code can have a chilling effect, to the point where comments aren't used where they are in fact "needed" (perhaps on the class, or groups of methods, if not on the methods). -- JimPerry I think this is largely about balance; I suspect people are attributing positions to each other that are more extreme than those actually held, and we're bouncing around between extremes. Fighting past wars rather than the current one. Also I suspect the balance depends on the programming language and environment used -- Smalltalk typically needing fewer comments than Java, and Java fewer than assembler. Lack of shared experience makes it harder to see the other fellows point of view. The only way forward (in my view) is to make this stuff explicit. -- DaveHarris ---- The first statement (''we specifically deprecate...'') is uncontroversial, since I haven't seen anyone advocate that programmers should write unclear source code and then garnish it with comments. (Surely that's not what you meant by your earlier pro-comment bias.) If the source code can be made clearer, by all means make it so (and ''then'' add comments that make it ''even clearer''). Perhaps this is just one of those half-empty/half-full things, but I fail to see how comment avoidance can be "fruitful". All the factors driving code clarity and refactoring still apply, so comments over and above those provide even more and better communication. It doesn't take much time to write a comment, and they needn't interfere with reading the source code, so I don't see much cost. -- JimPerry Programmers who can't write clear code are unlikely to produce useful comments. And useless comments definitely have a cost. Every developer who sees them will have to read them or read around them. It's more productive and easier to teach programmers to write clear code than to teach them to comment well. -- KevinCline ---- One of my current projects involves deciphering CeeLanguage and AssemblyLanguage code written for small devices and which implements bit-level and byte-level InterIntegratedCircuit protocol drivers. There are ISRs that are essentially uncommented because all the engineers that worked on this, 8 years ago, knew what they'd built and how it would all work together. A large amount of time has been spent digging up original authors and poring over project and debug docs trying to get a handle on why a particular delay constant was used, why interrupts were disabled at a certain point, and why ISRs (which should do something simple and leave) have become two-page state machines. Comments strategically placed in the code to explain some of the (occasionally heinous) compromises would have saved me a month at least. My vote is for lucid, expository comments. -- GarryHamilton I totally agree, but I have the urge to explicitly state that the nature of AssemblyLanguage greatly increases the need for comments. -- JoeWeaver And I would concur. So at what point along the ladder of languages does the language form and syntax itself assume the burden of comments? -- gh Is this an example of need for comments or a need for refactoring? For the parts in C, any refactoring not involving inheritance can be applied. Although one could simulate inheritance, I think in this case that the cure may be worse than the disease. As for the assembly portions, carefully review what really needs to be done in assembly and port the remainder to C. Also, if one has a really good assembler, assembly can rival C in clarity (but what I would qualify as a really good assembler is very rare). -- WayneMack ---- No Comment /* ie no comment on this article */ -- Malek BADI ---- Well-written code makes it easy to see ''what'' is being done. In the minority of cases where it isn't obvious, good comments explain ''why'' it is being done. Works for me... -- DanMuller ---- One other thing... while some suggest that descriptive method and identifier names remove the need for comments (see IdentifiersAreComments and similar topics), there are situations where you are using a 3rd party Library or platform-specific SDK/API that might not have descriptive names. Again, a place where Comments are beneficial. For example, '''Z''''''wMakeTemporaryObject'''... Does this method create a "temporary object", or mark an existing object as "temporary"? What kind of "object" does it create/change? Going along with what I said above: I believe it is incorrect to assume that other developers have the same understanding/experience/education as you do. As such, it is incorrect to assume that just because the code is clear '''to you''', it will be clear to others as well *. I am sure ''someone'' thought that '''Z''''''wMakeTemporaryObject''' was a completely clear identifier. '''Z''''''wMakeTemporaryObject''' is a Win32 Kernel Mode (Driver) function. Despite its name, it is documented as a function that ''changes the attributes of an object to make it temporary''. Perhaps '''Z''''''wMakeObjectTemporary''' would have been a better name...? (* As I have said to someone in the past, ''just because '''you''' do not know what I am talking about, that does not mean that '''I''' do not''.) -- JamesTwine ''On the other hand, it might mean you haven't communicated clearly what you are talking about. Comments are for communication to people - other team members, future maintainers, yourself three months from now (or three weeks!). But using comments has disadvantages which you can avoid if you just write clear, expressive code instead. If the code is unclear you should fix the code. Use comments only as your last resort, or to express things the code can not clearly express.'' My point above must be getting missed - put another way, if I was a math major and used clearly (but mathematically) named identifiers in my code, someone with less math experience may not get what I am doing because they do not understand the nomenclature (yes, some developers do not understand "Epsilon" in the context of doing floating point operations). Comments, when presented in a natural language, can bridge this gap. If English is the baseline, then we can all understand clear and expressive English. Naming conventions (clear and expressive code) does not have a common baseline that I am aware of, and I have seen lots of code in my day. -- JamesTwine ---- IDE's should have a simple toggle option to make the code more visible if the comments are taking up too much real estate. ''Some do. Both Eclipse 3.1.x and Microsoft Visual Studio 2005 allow you to either collapse comments to show only a single line, or expand to display the full text. Nice, this.'' -- DaveVoorhis Wrong. A SIMPLE TOGGLE option means you click one button and all comments on the whole page disappear/reappear. Shuffling through pages and clicking each plus/minus sign to non-inlined comments and still having a comment line visible is so lame it isn't worth mentioning. ''You are right that a SIMPLE TOGGLE option means you click one button and all comments on the whole page disappear/reappear. You are '''WRONG''' when you think Visual Studio doesn't have that. It does - Ctrl+M, L. It's true that Eclipse 3.1 is a bit lame - you can only expand all (using Ctrl+Numpad*), you can't collapse all. Reading between the lines of http://download.eclipse.org/eclipse/downloads/drops/S-3.2M1-200508111530/eclipse-news-M1.html suggests Eclipse 3.2 will fix this.'' -- DaveVoorhis ---- See WellCommentedCode, ToDo, FixmeComment, HeadlinesTechnique ---- CategoryCodingIssues