Slashdot Mirror
Comments are More Important than Code
CowboyRobot writes "I was going through some code from 2002, frustrated at the lack of comments, cursing the moron who put this spaghetti together, only to realize later that I was the moron who had written it.
An essay titled Comments Are More Important Than Code goes through the arguments that seem obvious only in hindsight - that 'self-documenting' code is good but not enough, that we should be able to write code based on good documentation, not the other way around, and that the thing that separates human-written code from computer-generated code is that our stuff is readable to future programmers.
But I go through this argument with my colleagues, who say that using short, descriptive variable names 'should' be enough as long as the code is well-organized.
Who's right?"
I used to grade student's code as a TA at my university, and I'll tell you what is more annoying than NO comments, this:
/* print "Encrypt message..." to the console */
printf("Encrypt message...");
and then followed by about 150 lines of uncommented spaghetti code
____
~ |rip/\/\aster /\/\onkey
Just go ahead and use the long names, that alone will reduce documentation/commenting
--Joey
Has he read the ones here?
Before any liberals are tempted to mod up one of my comments, a word of warning: I'm actually making fun of you.
...where comments are more important than articles.
Take off every sig. For great justice.
How about Perl's POD Documentation? I do a lot of hacking of Matt Simerson's Mail::Toaster and Nictool projects, and I find that the Perl POD Documentation system, combined with well-named variables is easy on the eyes, and leads to it being well interpreted by an outsider.
May this post be indexed by spiders, and archived for all to see as my Internet epitaph.
Always comment. Always. I'm not a career coder, but I've done enough to know that if it's a project of any noticeable size at all, and you intend to read the code later, take the extra few seconds and COMMENT THE STUPID THING. It makes life a lot easier. The only thing that probably doesn't need commenting is a simple BAT file or a shell script. Comment!
This works for code I write that nobody else will ever maintain. Even then I can get tripped up, I'll have to lean back in my chair and try to remember what I was thinking when I wrote the code.
But if you write code you're getting paid for, or code for an organization, anything but personal stuff, write good comments. Variable names might give a good idea about what data the variable holds, but it does not tell us much about how it is used.
When I took my first programming class, the most frustrating part was the documentation. I thought it was retarded and stupid and a waste of time. But now I realize it is very important once you write something more significant than "Hello World".
Rosco: "If brains were gunpowder, Enos couldn't blow his nose."
In my opinion, comments are useful -- but literate programming is where it's at if you're looking for the best way to document your code.
Knuth did a lot of work in the area -- if I remember correctly, all of the sources to TeX are written in a style understood by the "web" literate programming tool.
There was also a good article by one of the Perl folks (Nathan Torkington? M.J. Dominus? Chromatic? I can't remember.) on POD, and how although POD wasn't literate programming, it was still useful. That article was great in that it showed a middle ground that may be more palatable to your non-LP-fanatic programmer.
That being said, I prefer full-on LP for large projects.
unixkb.com -- articles on practical Unix issues.
i do a lot of code reviews at work and nothing makes me happier than good comments.
but just putting a bunch of blocks of comments that are like "get customer", "build record", etc are basically useless. If you use programming by intent then its more or less obvious that the code
GetCustomerFromDatabase(foo)
is going to do something with a database and get a customer. a comment telling me that is useless.
what i like to do is write a few paragraphs of text at the top of a function. it explains my general approach, why im doing certain things the way i am, why im not doing other things, and why the function even exists.
essentially the comments should be enough that anyone that knew the problem space ought to be able to read them and come up with more or less a similar implementation.
then, in the body of the method anytime i do something that i feel isn't completely obvious, i put a 1 or 2 liner infront of, i.e. "we have to do this because zergs are sensitive"
the end result of all of this is that code reviews can see what you were thinking at the time the code was written.. and you're documenting assumptions about the problem, the apis, your understanding of the language, etc, all right in the code. it makes finding errors pretty easy.. someone that can't even read source code can read the comments and get an idea of the correctness of your approach.
My opinions are my own, and do not necessarily represent those of my employer.
"Don't get suckered in by the comments -- they can be terribly misleading. Debug only code."
--Dave Storer
I want a new world. I think this one is broken.
Variable names should be proportional to the size of their scope within the code.
"There's a subtle reason that programmers always want to throw away the code and start over. The reason is that they think the old code is a mess. And here is the interesting observation: they are probably wrong. The reason that they think the old code is a mess is because of a cardinal, fundamental law of programming:
0 69.html
It's harder to read code than to write it."
From Joel on Software
http://www.joelonsoftware.com/articles/fog0000000
Always comment.
I hope that after I die the one word people use to describe me is "resurrected."
Why on earth do we even have commenting? I mean, we went through the whole programming language concept precisely to make instructions to computers human-readable. Ideally, commenting should be obsolete - the language and its syntax should make it obvious what needs to be done.
If it turns out that after all that, our code still isn't intelligible, then isn't this some monumental failure of C, Java, BASIC and the rest, whose whole raison d'etre is to make weird things make sense?
If the comments are clear, a better programmer than you can come along later and say "What the hell was this guy doing?" and then replace your lines of fumbling crap with much cleaner/clearer code.
It's the difference between being able to see what you were trying to do vs. figuring out what you actually did.
Call it "Intent Oriented Programming" if you want.
Simple Machines in Higher Dimensions
Comments are a maintenence nightmare. They get out of sync with the code, and (especially when the code is bad to begin with) people read them instead of the code.
That means over time the human's understanding of what the program does starts to diverge from the computer's understanding.
This is not good.
If something is too hard to understand the way it is written without comments, it should be rewritten. You will save time in the long run, trust me.
Remember the old adage: Don't get suckered in by the comments--the bug is in the code.
--MarkusQ
I disagree. India has more engineers than the USA. And these are smart people. Some of them already know english, and others will have to learn. India is a country with too much poverty and so little oppertunity, that when a young kid is given a chance, he'll learn it all. They are lean (paid little) and hungry (willing to learn). In the USA, we expect $100 an hour to consult, one place I worked at hired an Arthur Anderson consulting team and the lead got over $300 an hour. I bet he would be *insulted* to have to work for $20 an hour. Are you going to tell me that the guy in India won't take that wage?
If it means people in India will have to learn english, they will learn english the same way they get their engineering degrees. They will study their asses off like their lives depend on it.
If people in the USA have half a chance, now is the time to take advantage of it and produce a better product than they do in India. Leverege every advantage we have, because the competition is getting better.
We could say how the Bush administration is screwing us, and to a large extent they are. We never should have let factories leave the USA to mexico. We never should have let outsourcing happen. I hope future presidents start raising the tariff, and force American companies back in the USA. But maybe we need to get a little more lean. It is hard for the avarage employee to give a fuck when you see the CEO get a bonus when he lays people off, or scum like enron managment steal the pensions of employees, but what other option do we have? Change the tax code to tax the wealthiest at a higher rate and pump that money back to the poor? Maybe raise the luxery tax rate? Increase the estate tax? Break monopolies?
Rosco: "If brains were gunpowder, Enos couldn't blow his nose."
You are absolutely right. Some of the better design processes (to me) have involved turning the initial documentation into skeleton code, then writing comments around all the functions and classes that describe exactly what the program is supposed to do. Not only does it provide for excellent commenting and understandable code, it is immensely helpful in the writing of these functions.
/*retrieves the key 'SS#' from row r*/ may seem like overkill at first, but people who go over my work later don't even have to read the function for the code (unless they suspect the function is the source of a bug). They know what it is supposed to do, and a written out comment is generally clearer than a pre:post: with the bare minimum of description that some people prefer.
Having a function named "getKey(row r)" with a comment saying
UsngShrtCmtsIsOftNotEnghAsOneMyNdToReWrtShtInTheFt r.
The problem is usually functions that are too long and are not orthogonal. Write short, orthogonal functions and you'll see your need for heavy commenting go away along with the need for long variable names.
JEF RASKIN, professor of computer science at the University of Chicago, is best known for his book, The Humane Interface (Addison-Wesley, 2000), and for having created the Macintosh project at Apple. He holds many interface patents, consults for companies around the world, and is often called upon as a speaker at conferences, seminars, and universities. His current project, The Humane Environment (http://humane.sourceforge.net/home/index.html), is attracting interest in both the computer science and business worlds.
For those who don't know (which apparently includes whoever is in charge of the linked article), Jef Raskin passed away this february. You can view the official press release, or read more about his contributions to computer science. I don't know when the article was written, but it seems it should mention that Raskin has passed away. In any case, his advice about commenting is good, just as his advice on user-interface design has always been lucid and helpful.
You need that comment?
if (kbd_input_rcvd)
{
process_input();
}
is not clear?
I think properly modularizing your code (breaking process_input() into its own function), and properly documenting the modules (defining good documentation of input, output, exception conditions, return values, side-effects) is more effective than writing verbose comments (like the one you've noted) in poorly segmented code.
This whole discussion is a bit short sighted. The better and clearer your code is, the fewer comments will be necessary. The more useful comments you add, the less time will be necessary parsing and understanding clear code. The better your design overall is, the less code reading overall will be required, because you'll have documentation outside of your code that explains how the system works, and where you need to go make changes. Saying one is more important than another is silly.
-Greg
Imagine my relief when I came upon a helpful comment:
All it took was one comment to put my mind to rest: no, it's not just me being stupid in the present. This code seemed this terrible back then, too.
Comments save the day once again.
If it turns out that after all that, our code still isn't intelligible, then isn't this some monumental failure of C, Java, BASIC and the rest, whose whole raison d'etre is to make weird things make sense?
This is not algebra in high school where you lose points for not showing your work. This is the real world where an application might have 100's of lines of codes, maybe 1000's. It might be a bunch of classes in java working together. And then there is the logic, the work flow.
Plus, many companies use peer review for raises and advancement. If your peers have a hard time understanding your code, it will hurt you later.
Most people today don't work 30 years for one company. That means someone else will get stuck with your code.
Now either you will give that person months to go through all the code, to try and figure out how it works, or you will have code with comments that will help him hit the ground running.
Rosco: "If brains were gunpowder, Enos couldn't blow his nose."
The above would be far more useful like this:Now the intent of the method is clear, and anyone coming along who wonders why it's hard coded will know under what circumstances they should change it to a formula (namely, if MyClass becomes capable of meeting the Magilla criteria).
Comments can be good, but they should always be a guidepost to the intent of a block of code, and not attempt to explain how the code achieves that goal.
Stop-Prism.org: Opt Out of Surveillance
I found that writing the comments *first* my methods/functions is the way to go. This helps me organize my thoughts and makes finding where I should be refactoring much easier. After writing the comments, I fill in the code. By doing so, my comments focus more on the concepts and less on just restating what the code does.
Of course, there are always exceptions. When I was writing low-level code that manipulated hardware registers, I wrote a multi-line comment before each line of bit-fiddling code, complete with what the code did and a cross-reference into the hardware manual. Something like:
What a fool believes, he sees, no wise man has the power to reason away.
Surely commenting comes as a result of a good design practice.
You start with a functional spec, from which a design spec is derived.
The design spec is then broken into functional units, which are each divided further and further until the code itself seems obvious.
The final design is given a walk-through to verify with peers.
This design could pretty much be converted into a set of comments, each of which describes how the code should function.
The problem comes when coders just give it a go, write stuff on the fly and don't bother with design. It could be brilliant code, but most often it's just plugging local holes without reference to the overall design.
Comments are generally a good coding practice, and should fall naturally out of a good design phase.
I find that for simple code that requires little thought, little in the way of comments is required. Sometimes comments just get in the way as the code progresses over time, and the comments don't. It's better to code with long descriptive variable names, and structures then depend on comments.
//Customer ID structure // ID number for the customer // Agent Name // Customer Name
For example which would you rather read.
#define AgentNameLen 41
#define CustomerNameLen 51
struct CustomerID
{
int CustomerID;
char AgentName[AgentNameLen];
char CustomerName[CustomerNameLen];
};
or
struct CoID
{
int ID;
char AName[41];
char CName[51];
};
To me the first is much more clear, and throughout the code will be obvious as to it's use. The second is mildly clear, but will degrade as new things get added to the structure.
The first also allows things like
for(int i=0;iAgentNameLen;i++)
which makes it very clear that you are iterating throught the agent name.
Algorithm's should be documented, as much as possible, at the top of the function, and any function that takes more then a screen should be looked at to see if it can be broken up into smaller functions.
(Almost) Always code towards maintainability, never speed. Usually it pays off within the year.
So to sum up. In order of importance:
80% code clearly with an eye towards maintainablity
20% comment
Don't laugh. As an old school COBOL programmer in my youth, documentation was everything. Now that other languages have come along, you really need to document what you do, you can't just be lazy and not be willing to explain what your code does, This is what is happening to every program tha I see (C++. and M). Poor documentation, poorly written code, and very little commentary on what the particular function does.
My spin on this, your are a very poor communicator to your co-workers if you can not put a few simple words to a function in your program.
There are three things the poor maintainance programmer who has to maintain your code needs to know: The What, the Why, and the How.
The What: What is this code trying to do. This is where your design documents come in, as they tell what the overall goal of the program is.
The Why: Why are you doing what you are doing? Why are you writing to this hardware register twice? Why do you divide this value by 1800 here? This is where comments are needed - to explain that the hardware sometimes doesn't take the value on the read, or that the nominal deviation of this signal is 1800 Hz.
The How: How are you getting the work done. This is where well written code with well chosen variable names comes in.
www.eFax.com are spammers
Out of date comments are far far worse than none, and this happens with absolute certainty.
People will usually update variable names, but they won't update comments, especially when the IDE makes comments a different colour - your eyes don't even see them after a while.
You think spaghetti code is bad with no comments - try it with misleading comments.
Servlet v2.4 container in a single 161KB jar file ? Try Winstone
Having RTFA, I can see what he's trying to get at, but as someone who has (unfortunately) found himself spending most of my 10 year career in programming cleaning up other people's poop. At first I thought it was because I must have done something wrong that I kept ending up being assigned this work, but as I came to realise, it was because I make the code better than I found it and I have a knack for fixing stuff other people give up on. I also had silly managers who assign work to the people least qualified to do it.
At any rate, some observations:
1. 20 lines of comments "documenting" your code before you write it (or even after you write it) is far less useful than writing the code COHERENTLY and CORRECTLY in the first place.
Last month, I had a 1200 (yes 1,200) line method with huge blocks of documentation before big pieces of code. I still can't quite tell you what it thought it was doing. The code was a for loop wrapping around code to handle 3 different and mutually exclusive situations. Instead of identifying which of the 3 situations it was and creating a method for each situation, the person just stuffed it all in with lots of comments documenting everything the article's author said. The code was still unmaintainable.
2. Comments are useless unless they are kept up to date
Part of the reason that code was so difficult to figure out was because most of those big verbose documentation comments referred to a completely different implementation. After the programmer had written the first case, she encountered some other bad cases and eventually had to completely change a block of code embedded in this 1200 line for-loop. The code was now correct, but the comments no longer had anything to do with that block of code.
3. Don't be clever when you can be clear
I have made a solemn vow to hunt down and hurt anyone who puts "clever" code in my project. I am so sick of trying to figure out what some obfuscated piece of code in C, C++ or even SmallTalk is doing. And find out it was just a "clever" way of doing something pretty straight forward like iterating over a list. There was no speed gain from the clever trick, and the code wasn't even a bottleneck to begin with. *sigh*
4. If you don't know how to solve the problem, write some experiment code in a separate app to figure it out. Then take the time to do the "right" thing in the production code.
3 days from final for a video game. The CD streaming library for the Sony Playstation was making this strange "hic-up" sound at rare moments. By this time, the original author of this code has long since gone to another company. So I plunge into the code and found that the original programmer didn't know how to write streaming code so he created this hack of a hack of a hack of a test (ad nauseum). The code was programmed by accident, not design. No amount of comment before coding could help this. If the author had dumped the code, wrote documentation describing everything he learned then wrote the code, things would have been a lot better.
5. Unrelated to comments, but use variable names that make sense. Don't name them arbitrarily or to amuse yourself!
That CD sound streamer code I mentioned above used quirky names for variables. Can you tell what "little_ninja" is supposed to be just from the name? When I confronted the coder about this quirk of his (in another library he wrote), he got all huffy and didn't understand why people didn't appreciate his little puzzles or his sense of humor. It galls me he still earns a paycheck in the industry.
The bitter lessons of a veteran coder: http://bitterprogrammer.blogspot.com
I kid you not, this is real code my supervisor writes.
Note that this is matlab code, where commas are both an end-of-statement indicator (it's also possible to use just a semicolon), and an array index separator. The nice thing about this code, is that I can at least guess where most of the variable names come from. Oh, and there was *no* line break in the original code. Hooray for the avoidance of those wasteful '/n' characters?!?!
To answer the original poster: yes, comments are of vital importance.
Then again, if a program is structured right, things can be organized into sections, each of which is then commented, as opposed to a bunch of seemingly random lines with comments spaced throughout. Sometimes the layout of code, in conjunction with good variable names, is the best possible method of commenting it. The one thing comments are good for is to assure that someone not familiar with the particular language being used, will still understand the purpose of the code.
program.files.each do | class |
class.methods.sort.each do | method |
5.times { method.refactor! unless method.elegant? }
end
if problem_domain > current_language
choices << comp.lang.each
current_language = choices.best
project.restart
evangelise(current_language)
end
end
comments << intentions.remove(implimentation_details)
puts comments
def refactor!
method.split! unless method.size < Too_Big
method.rename! unless method.name.clear?
end
def evangelise(lang)
slashdot.comment.post
puts "#{lang} is the only real language"
end
goto (1.0/0.0) and $beyond
http://www.rubygarden.org/ruby?MoviesTheRubyWay
Well, that assumes that you have a nice, clear set of steps (like the example above). However, if you have a series of very complicated, non-intuitive steps that MUST be done, then commenting is pretty much essential.
XML is like violence. If it doesn't solve the problem, use more.
In "Literate Programming" the comments are all important and the code itself is trivialized. The code, as Jef told me, is like "raisons in the muffin of the comments." There are paragraphs of verbiage which might go on about the history of the project, why certain features were discarded, etc., etc, and might not even explain what the following line or two of code was concerned with.
It's really very difficult to deal with code that has been written in this style ("literatized?" ) since the actual structure of the program is severly obscured. It serves as an example of how overdoing a good thing is usually a bad thing.
Jef was a nice guy, and I recommend his book, "The Humane Interface" for its many interesting ideas. His attempt to put them into practice in the Archy project http://rchi.raskincenter.org/aboutrchi/index.php/, was not completed before his death. Even for that, Archy is very close to his vision.
But since Jef was in many ways an extremist, one can demonstrate in Archy his pushing of his concepts to the limit resulted in the end fully maching his goals. Somewhat like "Literate Programming", in fact.
I think that BOTH the comments and the code need to be readable. I've seen code with lots of great descriptive comments, but when you look at the actual code you can't tell if it does what the comments say it's supposed to do. The same holds true for the reverse. I've see code that's well structed, readable, descriptive variable names, etc. But without some comments about how all the pieces fit together the code can still be confusing.
The true useful skill lies in reading sloppy and/or wizardly code. Some people think that they have job security if they write impenetrable code, but then they can just be fired and all their code rewritten. If you can read others' "unmaintainable" code, you enable your employer to save money by not having to rewrite everything the guy they just fired wrote. So they'll want to keep you around as they fire/downsize everyone else. I It doesn't really matter what kind of code you write, since you can read whatever. advise everyone to start reading up on the Obfuscated C Contest, and practice figuring out what evertyhing does. Then you can handle any kind of code thrown at you, and the code you actually write becomes of secondary importance.
Definitely not. No matter how clear your code is, it only gives you an idea of what is going on the small scale. You often need comments to describe your big-picture motivation. But the comments have to be good too.
Here's a classic bad comment:That's useless. But a comment can help:No matter how clear you write the code you're not going to get that much understanding without a comment.
It's just a simple example off the top of my head, but that's how I use comments. The code clarity is all that's needed to tell what you are doing, but comments can tell you why you are doing it. You need both for truly maintainable code.
Cheers.
The problem with comments is there is no constraint to keep them...
Code Reviews help, but not enough.
There is a better way. It is called Test Driven Development. Tests are the least ambiguous, most correct and current commentary on the code. They are also always at the correct (higher) semantic level than just paraphrasing the code.
Given a choice of reading comments or reading well structured tests, I will read tests any day. I at least know if they run, that they are true.
Google knows.
My learning experience about commenting code was a difficult one. Like many, while in college I wrote the code and then went back to comment it so the profs were happy.
Then I did a co-op with an automated storage/retreival systems company in their software department. One of the processes involved in a communications system needed some work. The code was licensed from another company in another country. There was no documentation for this communications system. There was very little commenting in the code. Luckily it wasn't in a foreign language. Unluckily it was wrong, apparently the structure of this program was similar to that of another, which was mostly gutted and rewritten, but a few old-program comments survived to be the ONLY comments in the new program.
Sure, the sources could be reverse engineered to provide the documentation required. I did it. It took a few weeks.
After that, I didn't leave comments for last anymore. It's been a good thing. I now work for a semiconductor design company and often write perl scripts or skill-language scripts to automate tedious tasks. I think I'm abou thte only one in the office that comments such scripts in any way. It's nice to read what stuff does when I have to revisit code many months or years later. I hate having to revisit someone else's code because it's nearly guaranteed to be completely barren of anything human-readable.
Listen up kids! Commenting is GOOD! Your professors aren't just being jerks. Learn the easy way and hopefully save yourself a great deal of trouble with your own code. Other people's code will always suck, but your own shouldn't have to.
I had a co-worker who needed a little help with his program. It was C code, but all the semicolons were in column 80, arranged in a nice column. Yikes. He casually said "what, you've never seen that?". Turns out that part of his problem was that he was using float to represent a byte position in an extremely large file. He knew enough that UINT32 wouldn't do it, but ...
HIV Crosses Species Barrier... into Muppets
whose name escapes me at the moment. But the idea is that you write comments that are like "psuedo-code" but much more English-like than ordinary psuedo-code. Then you refine the comments down further and further until you replace the lowest-level comments with individual statements, and the higher-level comments stay in as documentation. I remember trying this once and, while overkill for the simple project I was doing, I wrote some damn fine (and readable!) code that way.
If it's not one thing it's your mother.
as a full-time student who worked part time during summmers coding a php/mysql/flash based website... i know exactly how important comments can be. last summer, i'd have to go back to code i wrote the year before in order to update it or something along those lines, and i'd stare at it for hours thinking... "wtf is the point of this? i know it has some point, but i can't put my finger on it!" since then, although i have done very little as i was replaced by an immigrant from india... (grrr).. i have pledged to make decent comments in my code that detail what in god's name is going on.
1. Comment each function
- Function name
- what it does
- parameters
parameter name - what is is for and any restrictions on it (i.e., must not be null)
- return value (all possible return values)
2. Add comments to each file you modify so that over time, the file becomes better documented
3. Add ASSERT() like comments and ASSERT() or equivalent to your code
4. Use dividing comments like a line of dashes to seperate blocks of code
5. Put in a '?' comment for code that you do not understand (good for function headers)
6. Avoid stupid naming schemes for your local variables since that makes it harder to comment
7. Review your code for both logic and comment completeness after you code it before committing it to version control
8. Tag your bug fixes, code enhancements with a comment followed by a dash, date, and your initials. This is essential for large projects or for anything you will be working on for more than 6 months.
9. Format your comments so that multiple line comments line up on the left hand side (increases readability)
10. Don't count on java doc or equivalent as being good enough code documentation.
GRANDPARENT: Especially if you change the code and now the comments are wrong
PARENT: You're incompetent if you don't change the comments to match the code. You're equally incompetent if you come across incorrect comments and leave them in. You're supposed to the job, so do it...
PARENT: As Fred Brooks said, "There is no silver bullet."
A database backend would go a long ways towards providing a silver bullet, i.e. if instead of writing your code to an ASCII text file, you were writing to a document management system that kept doubly linked associations between the lines of code and the comments associated with those lines of code, and if code/comment pairs had dirty bits, so that if you changed one [e.g. the code], then the dirty bit wouldn't get changed to clean until you verified that the other [e.g. the comment] was correct, then that would go a long way towards solving the problem.
I think we are still in the infancy of code/documentation/database integration, however.
If it was hard to write, it should be hard to read.
Steve's Computer Service, Hobbs, NM
Hmm. If you have a picture in your brain, you should be able to describe it in plain language. If you can't do that, then the code that implements it is of questionable validity. It doesn't make the code bad, but it does imply that the code is going to be difficult to follow.
"People who do stupid things with hazardous materials often die." -- Jim Davidson on alt.folklore.urban
I opened his listing (printed on non-recycled 11x14 paper), and was surprised to find the listing double-spaced. I tried to figure out how he did it (assuming it was an obscure parameter on the job control card), and eventually realized that he had inserted a blank comment between every line of code (ignore and forgive the periods; I had trouble indenting):
Understand that this meant that, while at the keypunch, he took the time to type a single "C", then feed a new card (taking a couple of seconds), before entering another line of code. (Not to mention the waste of expensive card stock.)
When I asked why he took the time to generate all those blank cards, he answered, sincerely, (wait for it...):
"The professor said the program would be easier to debug if we had a lot of comments."
I have written programs in both raw and literate programming style, i prefer the latter. In fact, i wrote a literate-program pre-processor to write programs, and it made the program easier to write and more bug-free.
In literate programming, you rely on a pre-processor to make the output production, so you are free to put things together as you want. What this means, is that bracketing code (eg open, close files), can be written in the same block, which are invoked separately.
The main program then ends up looking like a rough scetch, full of commands to include other bits. With wing comments, it is easy to see what is going on.
One uses a folding editor to search for strings like "!topic". This will not show you a consolidated index, but you can use it to also show where you're are, and any missing bugs.
On the main, Jon Bentley's comments on Literate Programming are fair (that is, it creates a good environment for writing single-purpose code), but one needs to consider the context the program is written for.
The form i use was specifically designed to allow all sorts of text-output, so the same file can make as output, eg .CMD, .REX, .TXT and .HTM output, which means that when you run the script you get a perfectly matched set of files, all correctly pointing to each other.
OS/2 - because choice is a terrible thing to waste.
In assembly, this is totally necessary. For example, this old DOS code
Obviously, without the comments, you won't understand what I wanted to do, and you could for example suppose that I could have replaced 'mov bl,7' by 'mov bl,ah' since they were identical, which was pure coincidence.
In higher level code, on tree-walking functions, or in finite state machines, you need to comment your intent, because you'll always put bugs, and the only thing which counts is the algorithm that you validated by hand on paper. So you explain what you tried to do, and anybody reading your code (including you) will then understand why some transitions don't work as expected.
I often ask friends to comment their interfaces so that even themselves know if their input is valid. Example below:
But on the other end, I hate useless comments such as all cited in other posts (eg: print "x" on console). They make it difficult to read code.
Following such rules will generally help people understand your code, and help yourself maintaining it over the years. That's also one reason I quickly forgotten how to code in perl
Willy
I can't believe noone has posted about this yet. Click here (or check /usr/src/linux/Documentation/CodingStyle) for Linus' witty and insightful views on this topic. Chapter 5 in particular.
Raj Against the Machine! http://social-butterfly.appspot.com/
Comments are important. However there are different types of comments each with varying degrees of priority. Comments are primarily code documentation. Code generally starts with some sort of design and design documents are the first stage of code documentation.
Designs don't have to be monolithic war and peace style documents, rather very high level documents describing the purpose of the code. This generally gives future maintainers of developers an idea of the effect changing the code will have on an application.
Class Documentation / API Documentation / Java Docs / Perl Docs / .Net XML Docs are in my opinion are the most important forms of code documentation. I very much enjoy reading articles about programming concepts and designs. But when I am coding, it is the API documentation that I spend most of the time reading. My favorite languages are those which provide a large library of useful classes that I can reuse. perl, php and Java have large online communities that produce reusable library. This has two effects.
Writing such small reusable libraries generally the documentation will be very good. Each reusable library has documentation that allows other programmers to figure out how to use them. This means people writing these libraries are not only good at writing reusable code. They are also good at instructing others about how to use such code. Over time they become experts at documentation and serve as role models for others developer. .Net is an example of a large development group accepting these practices and now trying to embrace such strategies. But there is a much more interesting aspect to this.
Developers using these libraries become very good at using libraries. As programmers become more experienced, they progressively become more adept at finding reusable code and being able to make it part of a consistent unified solution. Developers who are practicing these techniques are becoming very good at designing and documenting reusable code. Having this community of code exposes developers to an enormous amount of high quality well documented code. This not only allows them to be more efficient developers, but teaches them to be very efficient designers. These are the people who become the respected technical leaders and in the optimistic case your boss or the senior programmers on the projects for your work. Perhaps you are one of those programmers and other a benefiting from your use of such tactics.
The least import type of code comments are the one or two lines before the while loop. These types of comments document the code at a micro level. At this level you rarely need a lot of comments. In most cases a competent developer requires the ability to decompose the code and this level without a lot of comments. This type of comment is never the less on the forefront of most discussion about code comments. Less experienced developers general can figure out the code is difficult to maintain but may not know exactly why. Not having the experience to point at exactly what makes the code difficult to maintain they assume it lacks sufficient documentation. This argument seems almost immediately logical. Unfortunately there is a flaw in this logic.
Just because code is difficult to maintain or enhance does not indicate poor documentation. I have maintained lots of well documented code that required hundreds of hours of modification to fix simple bugs or implement small changes. Several years ago I was asked by my company to help when a new application was released to our clients. This code met the acceptable requirements for code documentation. Each file had a header with modification history including date and developer information. Comments we also placed liberally throughout the code. This projected resulted in a single release and is currently being rewritten from the ground up. When I was asked to assist with the analysis the code documentation helped us quickly conclude the application would not be a viable replac
I love telling this story...
// break
Last year I had a brief stint at a small software company that had just taken a project in-house that was developed by an outside contractor. My job was to take the code they'd just inherited (which no one there knew anything about) and add some features to it on a tight schedule. Documentation? What documentation?
The extent of all of the code comments it had was the following (and no, I'm not making this up):
if(...) {
break;
}
If that wasn't bad enough, I knew the original developer personally. She was a former professor of mine and I'd worked for her company only a few months before she had taken that contract.
As someone who has had to deal with code with descriptive names and no comments or docs to go with them: If you write such code, may you rot in the lowest level of hell along with traitors, used car salesmen, and people who answer cell phones during movies.
--GrouchoMarx
Card-carrying member of the EFF, FSF, and ACLU. Are you?
No joke, that was in production code from developer that I'm sure a lot of you would recognize. There was also something in there to the effect of:
But I didn't find that one, I just heard stories.
Nick
I think it's safe to say comments are for the benefit of those who have not assimilated their language, their APIs, etc. Sure, documenting interfaces is essential as well as how certain data structures are used. Most of the other comments I have seen are completely superfluous and only enhance the understanding of the uninitiated.
cat
Comments, at ***BEST***, tell you what the author of the comment *hopes* was going on, at the time it was written. The code that follows may well not do anything of the sort; it may have, at one point, only to have been re-written by somebody else at a later date; it may still do what was stated, though that's no longer what's needed.
;)
Yes, it takes longer, trying to grok uncommented spaghetti code, but doing so on a regular basis will help you develop a reputation for being able to fix any bug, anywhere, any time. It even allowed me to track down a bug in a now-defunct version of Borland C's optimizer, that produced incorrect code when two seemingly unrelated options were selected. There ain't *NO* amount of commenting in the source code that would have helped there.
Learn to do your job right. Don't depend on what was written in any comments. The compiler ignores comments; so should you. However, as damned few programmers actually know how to debug other people's code, and many are too lazy to read it like a compiler, do add comments to your own code. It makes the stuff easier for PHBs to read.
For those who want to grok code the way it's executed, I'd suggest you start like I did, by reading old obfuscated C code winners, and running them in your head, comparing what you got with what the computer got. You'll burn up a lot of scatch paper, but eventually, you'll see what I mean.
Lemon curry?
I'd say you're right, comments are more important. Clearly-written code should make how it's doing things obvious, yes. Comments, though, should say what is being done and why it's being done the way it is.
I want to laugh when I read it.
Some of it is funny.
Some of it is just scary.
The human mind can be a freakishly messed up thing.
http://mindprod.com/unmaindocumentation.html
It is part of a larger essay about writting crappy code.
Anybody that even comes close to software development
should check it out.
--- begin excerpts ---
Avoid Documenting the "Obvious" :
writing an airline reservation system, make sure there are at
least 25 places in the code that need to be modified if you were
to add another airline. Never document where they are. People who
come after you have no business modifying your code without
thoroughly understanding every line of it.
Units of Measure :
variable, input, output or parameter. e.g. feet, metres, cartons.
This is not so important in bean counting, but it is very important
in engineering work.
As a corollary, never document the units of measure of any conversion
constants, or how the values were derived.
It is mild cheating, but very effective, to salt the code with some
incorrect units of measure in the comments.
If you are feeling particularly malicious, make up your own unit of
measure; name it after yourself or some obscure person and never
define it. If somebody challenges you, tell them you did so that
you could use integer rather than floating point arithmetic.
On the Proper Use of Design Documents :
complicated algorithm, use the classic software engineering principles
of doing a sound design before beginning coding. Write an extremely
detailed design document that describes each step in a very complicated
algorithm. The more detailed this document is, the better.
In fact, the design doc should break the algorithm down into a hierarchy
of structured steps, described in a hierarchy of auto-numbered individual
paragraphs in the document. Use headings at least 5 deep. Make sure that
when you are done, you have broken the structure down so completely that
there are over 500 such auto-numbered paragraphs.
For example, one paragraph might be: (this is a real example)then... (and this is the kicker) when you write the code, for each of these paragraphs
you write a corresponding global function named:Do not document these functions. After all, that's what the
design document is for!
Since the design doc is auto-numbered, it will be extremely difficult
to keep it up to date with changes in the code (because the function
names, of course, are static, not auto-numbered.) This isn't a problem
for you because you will not try to keep the document up to date.
In fact, do everything you can to destroy all traces of the document.
Those who come after you should only be able to find one or two
contradictory, early drafts of the design document hidden on some
dusty shelving in the back room near the dead 286 computers.
--- end excerpts ---
I am surprised nobody has brought up literate programming yet. Completely flips over the relationship between code and comments. You are principally writing a document for human consumption. One in a while, you also toss in a little fragment of code for the computer's benefit.
The code should be written so that it is obviously WHAT it does.
:-) Like when I go "ok, it's doing that... But WHY?", I know that I should have put in a comment. But if I go "WHAT the f**k is it doing here", those lines should be rewritten.
The comment should explain WHY.
Not that I use that convention myself, but I often wish that I did
It's not just that the programs to write are small, it's that they're write-only. You write them once, get graded, that's it. We churn generation after generation of students who are taught that code is written once, then never ever maintained.
Sure, you learn lots of things about design, software engineering, etc, in university, but they're pure theory. And seemingly useless theory at the moment. There is _nothing_ to illustrate there why some code organization is good, and why spagetti code is bad. All those lessons about maintenance as wasted when you never have to maintain anything, nor ever write anything big enough.
So while I'll say your idea does have merit, I think it can be done better. Don't just give them 1000 lines of someone else's code. Make them keep building and expanding the same program until the last year.
E.g., ok, in introductory programming they had to write some 100 line trivial program. But don't throw it away. When the next course comes along, give them the assignment to change or expand that original program.
E.g., if at some point you also get a computer graphics course, make them add a graphics module to that program. GUI programming? Sure, add a GUI to it. Database programming? Sure, make it save the data in a database. YACC? Ok, make them add a small scripting language to it. Different language? Make them port it to that language. Etc.
Make it a part of the grade to explain _what_ had to be changed and _why_.
Eventually it _will_ grow to be 1000 lines, and then it will grow even larger. And more importantly it'll be example of why code has to be readable and maintainable.
A polar bear is a cartesian bear after a coordinate transform.
I don't understand why people don't use more descriptive variable names. For something stupidly simple like a counter in a 'for' loop, the iterating variable could easily be 'ctr' instead of 'c'. There is zero performance hit and everyone understands the code more clearly. TWO LETTERS, come on man!
Going further... in c++ member functions and variables should be more descriptive. For instance, in a variable length array class, (mMaxArrayLength, mCurrentArrayLength) are much much better than (max, len) which is the common lexicon.
I feel (at least in c++) that documentation should only be used to explain high level functionality, the inner workings of a fucntion/method should be evident by the variable/method/class names. It doesn't add code size or decrease performance in any way. And, with the advent of copy and paste, it doesn't really slow development time either.
BUT.... Even more important than that is consistancy. Whatever coding/documenting style is chosen for a particular project, for god sakes, stick with it. Nine out of ten coding/documenting styles will be exactly the same, with little changes here and there. The most important thing is be consistant with the whole project.
end of rant
Fast Federal Court and I.T.C. updates
I find that the most useful comments clarify the underlying code by adding something that may not be possible to get from the code itself. For example the intention of the code may or may not be clear (the code may be incorrect or it could 'mean' several things given the context) but a comment can be explicit about the intention.
The point is you are not repeating the code statements- you are adding information to the source code. This makes it a lot less likely the comment is going to go out of date. In many cases you can change code and the comment will still remain the same (you are still searching a hash for the RequestItemId- just doing it faster/better/correctly).
Programming is about translating concepts from a problem domain (Billing, Accounting, CRM, Networking, Memory Paging) into code (be it C, C++, Java, Perl, Pascal..). We endeavour to build functions, methods and objects that map to the problem domain (so we can display a picture, act on a button click, add a charge to a customer's bill...). But this translation inevitably has some tricky bits that are not clear from the code (what format is the time in? why do we have to mask of the data retrieved from disk? why aren't we validating the customer's username?). So it can be useful to put the 'original' (our intention) in there and any useful translation notes (the tricky or non-obvious bits) so that we can make it clear where something is done or not done deliberately- and when it is simply an error.
Good comments add information not necessarily obvious from code. That makes it tricky to write good comments since you have to look at the code as if you had never seen it before and ask: what isn't obvious about this? Which is why writing the comments before you write the code can be much more effective. After you've written the code it just feels like you are stating the obvious. Which it is- to you, at that moment in time.
The comments from the TAs about near useless comments was interesting.
Getting people to do any comments is a conversation in itself.
However, the TAs brought up a good point. It is not enough to put ANY comments in a file, you need to put GOOD comments in, but who teaches people what good commenting is?
What works for me is
- putting a small paragraph at the top of file
explaining, in general, what the file is for
( sort of like labeling a jar with the preserves
you just put into it )
- putting a 1-2 line description above each
non-trivial function
- putting a sentence fragment above each
significant or non intuitive ( coding around a
quirk ) block of code
I get compliments on how easy it is to understand and maintain my code( often resulting in me getting to asked to write more code - versus the folks who intentionally obscure things in the pursuit of job security ). I can also go back to code I wrote years ago and understand what it is going on.
I put comments in as I write the code, mostly, so it doesn't feel like a burden.
If anyone has any other good idea, please do tell, someone somewhere is likely to give it a try.
I teach computer programming part time at a local college - when students sign-up :(. 50% of their grade is based on their comments. I have spent too many years in industry to dismiss that value of good comments in code. Commenting first helps you think through your solution then you stomp down your code and clean-up your comments. Time and again this will take you LESS time and produce higher quality code then just banging away.
I used to be a technical writer. I really come at code form a documenter's point of view. I found that comments do more to CLEAN UP my code than anything else. Commenting really forces me to consider what I am looking at and what's I'm doing. Comments are great. Good code will never be self-documenting. There's more to good code than variable names. I use comments to describe intent. I use comments to point out idiosynchrasies, and why those are in the code. I use comments to explain the overall logic of the code, and the logic at specific points. All that helps me to find and fix problems faster. That helps me to know where in the code to add new code. That helps me to compare my intent with my execution. And more importantly, this helps the next person greatly.
The three items you seem to object to all have fairly legitimate uses in some computing contexts.
1. Comment each function
- Function name
Why do you need to repeat the name of the function? It's right there in the code.
Yes, and in some contexts that is precisely the problem. Depending on the language and editor(s) you are using, embedding the function names in comments can be very useful.
For example, if I use an "FC" command in a Unisys 2200 mainframe editor (say ED or UEDIT) to show all lines starting with "C" (comment lines) in a Fortran program, the results will be confusing if the function names themselves are not specified in a comment line. All I will see is comments with no context.
By adding the subroutine or function names in the related comments themselves, that missing context is restored.
5. Put in a '?' comment for code that you do not understand (good for function headers)
Code with personal annotations should never be released.
While I agree with this part,
If you don't understand it, you shouldn't be working with it; go find someone who does understand it instead, or stop and work it out.
this part of your comment seems limited to "perfect world" scenarios only.
I've spent most of my career working on mainframe code that was either originally written by people at other organizations or companies, or that was written so long ago that the original designers and coders were either retired or deceased.
When making a first pass at understanding such code, I've found it to be quite useful to leave various comments in the code so I have a good idea about my level of understanding the next time I have to come into that area of code.
I've also found such comments useful when left in the code by others, since it reflects their level of understanding as well. Some of the stuff I'm looking at now was originally coded in the early 80's and rewritten by my predecessor, and the comments he's placed in the code have proven to be invaluable to me, even though some of them were speculative in nature. Something like "What does this code do?" in his comments often alerts me to a tricky part in the logic that I'll want to pay special attention to.
FWIW, question marks and other comments/speculations are commonly used when working on someone else's previously-written code, at least in my experience, especially when that code is only intended for use in-house (the source is not released to customers).
8. Tag your bug fixes, code enhancements with a comment followed by a dash, date, and your initials. This is essential for large projects or for anything you will be working on for more than 6 months.
Once again, nothing with personal annotations should ever be released into source control. Not only should I not need to know who wrote or changed a particular snippet of code to fix a bug, I shouldn't even be able to tell by looking at the code.
When working on code that was written in-house, and which is intended to stay in-house, I *want* to know who made a certain change and why it was done. That type of notation can save me (or another support programmer) a lot of time.
While those types of details might be handled by the source control system(s) that you work with, keep in mind that some of us work on platforms where analogs to the UNIX-like source control systems many people are used to simply do not exist (and often such a thing isn't really needed).
When I did Unisys A-series mainframe contract work at a small company in southern Minnesota, they used the unparsed end of each COBOL line as a comment area, and one always placed their initials and a date there so people knew who did which changes and when those changes were created. The editor they used (CANDE) even had a special setting to automagically place a change mark on the end of each line that was modified.
A si
Mainframe/UNIX Bit Twiddler and long time Windows/Linux Hobbyist.
The Theorem Theorem: If If, Then Then.
To paraphrase Einstein: we should write as few comments as possible, but no fewer. The reason is that comments don't execute and therefore aren't constrained to tell the truth about the code. So anything about the code that can be said directly in the code ought to be because that makes what's been said inseparable from what actually happens when the program runs. If it can't be said in the code then it ought to be said in the tests. Tests don't force the code to conform to the properties that they describe but the do tell you if it doesn't. They are one step removed but still provable. The redundancy of saying the same thing in both the code and the tests is valuable because the difference in perspective forces a greater degree of precision and, therefore, a higher chance of correctness.
Saying the same thing again in comments is not useful from the perspective of correctness, so the value of redundancy in comments is limited to the value of redundancy in most communication: if it's done sparingly it adds emphasis, otherwise it's just a harmful distraction. The value of comments is that they can be used to say all of the things that couldn't be said in the code or in the tests. The best code expresses the vast majority of its important information in the code and the tests, but is not stingy about expressing all the rest of its important information in comments. Comments written in this way augment the code without distracting from it.
Remember:
I've seen cases where a fresh from school programmer turned 20,000 lines of complex, hard to understand code into 3,000. The complex code was written by a programmer with 20 years experience. (Hence my belief that you cannot be both a good programmer and a good musician)
This is a good example of code that can be improved for documentation and readability, actually. Instead of checking for negatives, which is backwards to normal thinking, you can assume a combination will not work, and then describe the combos that will work:
/* Ensure arguments are valid */
/* make sure argument order matches the order
/* loop through each potion combination */
/* check that the potion combi is filled in
/* check if this combination matches the
/* this combination works. Use its
/* make sure we're not returning junk */
Most of your code would look like this then:
PotionCombo potionCombos[] = {
{ WATER, SOIL, MUD }
{ WATER, BEER, CHEAP_BEER }
};
A comparatively small loop function can check the list:
/* checkPotionCombo
Check a given combination of potions,
returning the potion that results.
Returns: the combined potion, or an empty
flask if the mixture is invalid.
*/
function checkPotionCombo(Potion a, Potion b) {
REQUIRE(isValidPotion(a));
REQUIRE(isValidPotion(b));
Potion result = EMPTY_FLASK;
of our combination lists (lower potion
number first) */
a = min(a,b);
b = max(a,b);
for (i=0; i<NUM_POTION_COMBOS; ++i) {
properly */
assert(isValidPotion(potionCombos[i].a));
assert(isValidPotion(potionCombos[i].b));
assert(isValidPotion(potionCombos[i].result));
arguments
*/
if ((potionCombos[i].a == a)
&& (potionCombos[i].b == b)) {
result, and stop searching */
result = potionCombos[i].result;
break;
}
}
ENSURE(isValidPotion(result));
return result;
}