Posted by mareserinitatis in computers, research.
Tags: commenting, comments, computer, programming
While the title above may seem like a complaint about the blog, I am fairly certain that the lack of commentary is probably due to the lack of posting.
Instead, however, I feel like complaining about another issue (one I’ve likely addressed before): lack of comments in code. One thing that frustrates me about teaching students to program is that they are generally unaware of how important it is to comment your code, particularly when that code is for a research project and may need to be picked up by someone else.
I guess I’m getting old enough that I’ve had several instances of attempting to pick up an old piece of my own code and realizing what a horrible job I did in commenting. I’m now incredibly thorough when commenting my code so that I’ll be able to go back to it later and understand.
The real issue is, however, that no one ever taught me how to comment code. It’s something I had to figure out for myself. The only thing I ever saw was one brief section in Darnell and Margolis’ book. While I agree with the Do’s they listed, I strongly disagree with a couple of the Don’ts:
- Do not describe how a piece of code achieves its purpose. This should be obvious from the code itself.
- Do not repeat the code. Comments should contain additional information that cannot be construed from the code itself.
- Try not to use comments to explain the purpose of variables. Instead, use meaningful variable names.
While I agree with the second bullet, I’ve learned over time that the first and third are bunk. Specifically, there is this notion that well-written code should make it obvious as to what is being done. Maybe if you’re the only person looking at your code, but that’s usually not the case. As much as we would like to think that meaningful variable names will substitute for explanation in the comments, I’ve found that one person’s meaningful variables may not be that to another person and will probably require significant elaboration. Further, truly meaningful variable names often need to be rather long, and few people want to take the time to type out names that would be exceptionally clear. (And then there’s the programmer I knew who used exotic dancer’s names for his variables. His code was a nightmare to debug.)
The first bullet is the one that really irritates me, however. I have pulled up code I wrote from a class to use in another class and been completely confused because it had been years since I looked at it. During the second go-around, I realized there was a chance I may end up using it again, so I started adding things in. Specifically, I put in the comments that it was algorithm to do linear interpolation. I even put a reference to the book I got the algorithm from, including page numbers, and what the inputs would need to be (including format requirements) as well as the outputs. I mentioned what needed to be changed to use the code for other programs. Finally, I went through and explained what was happening in each step or loop and what the variables meant (e.g., k is a counter, c is the coefficient array). Without *all* this information, it was impossible to take the code I’d written and modify it for another use without putting in some significant effort.
The reason I went into such elaborate detail (and continue to do so) is that a lot of code, particularly when dealing with algorithms, is almost never intuitive. If that were intuitive, references like the numerical recipes books would be useless. (Well, they kind of are, but you know what I mean.) Therefore, contrary to the advice given above, comment everything, how it works, what your variables mean, etc. You and anyone else who uses your code later will be very appreciative.
Posted by mareserinitatis in education, teaching.
Tags: comments, evaluations, teaching
I suppose getting evals once a year (since I’m currently teaching only in the fall) is sort of like having an annual review.
I have to say that I’m rather pleased with this year’s review. Of my four sections, I did have one ‘dud’, where the scores were noticeably lower than others. However, in all classes, I generally was at or above the average. Given I have now earned a reputation for teaching the hardest sections of the course, I think I’m a bit proud of that.
I had all of four comments:
Pointless class!
She was very helpful when working on our schedules.
Does a very good job teaching everything.
The most interesting comment was this:
You assumed too much w/the final MATLAB assignment. People who have never programmed would never understand for loops and “if” statements.
I am amused that this person was so concerned about their peers that they felt the need to tell me I was expecting too much. Or maybe they were mad because they themselves didn’t understand and didn’t want to admit it.
I find it interesting because the whole point of the unit was to learn some basic programming…and I consider loops to be fairly fundamental. I also explained them in class. Even more important is that this student may not have clued in yet to the fact that one is supposed to learn new things in college, not just stuff that one knew before. That being said, the vast majority of the students were able to finish the assignment and did just fine.
I’ll just take it that I’ve officially reached “too high in the ivory tower” status.
Posted by mareserinitatis in engineering, papers, research.
Tags: comments, papers, reviewer comments
My husband just received some reviews of a paper on which he is a co-author, and there are a couple real gems here.
First: “Please improve English uses in the paper.”
And later: “Introduction can concise.”
While I appreciate where they’re going with this (and there were more similar comments), I think the pot needs to brush up on some grammar before pointing at the kettle.
I also blog at Engineer Blogs, home away from home to some of the best engineering blogs.
Doesn’t anyone ever comment any more? June 26, 2013
Posted by mareserinitatis in computers, research.Tags: commenting, comments, computer, programming
3 comments
While the title above may seem like a complaint about the blog, I am fairly certain that the lack of commentary is probably due to the lack of posting.
Instead, however, I feel like complaining about another issue (one I’ve likely addressed before): lack of comments in code. One thing that frustrates me about teaching students to program is that they are generally unaware of how important it is to comment your code, particularly when that code is for a research project and may need to be picked up by someone else.
I guess I’m getting old enough that I’ve had several instances of attempting to pick up an old piece of my own code and realizing what a horrible job I did in commenting. I’m now incredibly thorough when commenting my code so that I’ll be able to go back to it later and understand.
The real issue is, however, that no one ever taught me how to comment code. It’s something I had to figure out for myself. The only thing I ever saw was one brief section in Darnell and Margolis’ book. While I agree with the Do’s they listed, I strongly disagree with a couple of the Don’ts:
While I agree with the second bullet, I’ve learned over time that the first and third are bunk. Specifically, there is this notion that well-written code should make it obvious as to what is being done. Maybe if you’re the only person looking at your code, but that’s usually not the case. As much as we would like to think that meaningful variable names will substitute for explanation in the comments, I’ve found that one person’s meaningful variables may not be that to another person and will probably require significant elaboration. Further, truly meaningful variable names often need to be rather long, and few people want to take the time to type out names that would be exceptionally clear. (And then there’s the programmer I knew who used exotic dancer’s names for his variables. His code was a nightmare to debug.)
The first bullet is the one that really irritates me, however. I have pulled up code I wrote from a class to use in another class and been completely confused because it had been years since I looked at it. During the second go-around, I realized there was a chance I may end up using it again, so I started adding things in. Specifically, I put in the comments that it was algorithm to do linear interpolation. I even put a reference to the book I got the algorithm from, including page numbers, and what the inputs would need to be (including format requirements) as well as the outputs. I mentioned what needed to be changed to use the code for other programs. Finally, I went through and explained what was happening in each step or loop and what the variables meant (e.g., k is a counter, c is the coefficient array). Without *all* this information, it was impossible to take the code I’d written and modify it for another use without putting in some significant effort.
The reason I went into such elaborate detail (and continue to do so) is that a lot of code, particularly when dealing with algorithms, is almost never intuitive. If that were intuitive, references like the numerical recipes books would be useless. (Well, they kind of are, but you know what I mean.) Therefore, contrary to the advice given above, comment everything, how it works, what your variables mean, etc. You and anyone else who uses your code later will be very appreciative.