{Mods, let me know if inappropriate}

I am a research professor at the New Mexico Institute of Technology and am conducting a study that deals with program comprehension. If you have time, I'm looking for professonal programmers to take a survey located at

http://www.senseandusability.com/survey/survey.php

Thank you for your help.

I'm going to feature this on the homepage and edit the title to "Why Do You Comment Your Code?" and move it to the software development forum.

Would you be so kind as to share your findings/results?


My brother and a good family friend goes to New Mexico Tech so anything I can do to support the program, let me know!

Small world, My office across the hall from his class.

I've heard one of my coworkers talk a tiny bit about this, seems interesting and would like to see where it can go.

Interesting thing I do is, although I am the primary consumer of my own comments, I write them for others, because that makes more sense when I come back 2 years later and have forgotten most of the context surrounding it.

Thanks for the support, I'll keep all posted with what I find. If you (or brother and friends) are at NMT, by all means say hello! I'd be happy to talk more about this (as all researchers would be happy to talk about their own research!)

Hello,
I was wondering if you might clarify who you would like to participate. I missed the word "professonal" the first time I read your post.
I code in my free time when and/or when I'm bored and I do it for the organization where I volunteer(mostly simple web interfaces).
I wouldn't really consider myself a professional though.

You might consider making that slightly clearer on the survey page itself.

Per

I comment the code because of 2 reasons, 1) other people after me if are to maintain the software, update it, knows what each block does and how they are connected together. 2nd reason)Me, after several months or so, after finishing it up and starting another project you usually forget principles of the project, and comments are usually a good way to remind yourself what the code does.

professional = a person engaged in one of the learned professions.

I completed your survey, I'd be interested to see the results.

Im definently not a professional.
I comment my code so I can use it later.
especialy when I do somthing that is particularly different.
I never know if my brain will be thinking on the same line or not.
a problem that takes me about an hour to figure out at one time might take
me a day at another.

I don't comment code, much. There is one reason for it and that is maintainability; an option under represented on the survey. By this I mean, if a section of code looks atypical, the kind of thing a programmer might consider refactoring, state a reason why they shouldn't. There are lots of bits of code where you'll find yourself asking, "why the hell was it done like this" only to later find a technical constraint or buisness rule that forced it to be that way.

Code is human readable documentation. It is the documentation for producing something that is computer readable. Anyone who understands the language of that documenation should be able to read it. Comments are like footnotes for when the document itself needs something to strengthen it's point.

Some comments on the survey:

Question 7, "How important is it that other people understand your code?" doesn't undestand maintainability. After a few years, the programmer is "other people".

Question 9, real answer, comments are useful for maintaining code.

Question 12, "what is most important when trying to understand a new program?". Context need. Does this mean a program that the programmer has never seen before or one that's about to be written? I assumed the former. Real answer, a fundamental understanding of programming methodologies. Language isn't most important and "similar problem" is too vague.

Question 14, "How much information should be contained in a useful comment?", the options are, "As little as possible", "As much as needed". These are the same answer.

Question 15, for importance, options are "Code that works" and "Code that is easy to understand". Code that works is a given, if it doesn't work, it's not really a program. Code that is easy to understand is probably well factored, which is ideal. There may be an implicit assumption in this one that comments make code easier to understand? This is not the case. Well written code without comments breaking up the flow is easier for programmers to understand.

Question 16, "most efficient code possible" is to subjective to illicit a valid response. You can make very "efficient code" that is only marginally maintainable. You can make code that's well written, not the most efficient, or the quickest to write, but most maintainable. Heavily optimized code will always be "most efficient code possible" and a maintenance nightmare.

I comment my code so people who come back to it later know what is going on and sometimes i comment out chunks of the code that aren't currently needed at the time but could be used later.

Comments are great, especially if you are looking at someone else's code and trying to put everything together.

Hello, thanks to everyone so far for their help. I've fixed a flaw in the survey that only allowed one to enter a single digit in years of experience. Please let me know if you find any more bugs.

Let me explain the "professional" statement: I mean people who are not currently students (especially undergraduate students). Most studies of program comprehension were conducted on students because the researchers were often--like me--academics and they had a ready supply of participants for their studies in the form of their students. However, these findings are hard to generalize to real programmers--that is to say, people who are working in any capacity to code in the "real" world--because the realities of the workplace are much much different than the realities of college.

I'd also like to say thanks for the great points made above about the survey questions. I don't really want to comment on them until after the study has concluded, as I don't want to alter anyone's initial responses. However, if you've taken the survey and would like to discuss the questions I'd be happy to do so offline, just send me a note.

Thanks again

Let me clarify a bit. I was fairly certain(just not 100%) about the definition of professional, which is why I didn't do the survey.

I just wanted to recommend that you put some kind of clarification on the survey page itself because I'm sure there will be people who miss the word "professional" in your original post and don't necessarily scroll down and read these posts until after they have completed it.

Per