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 computers, engineering, research, science.
Tags: commenting, programming
Like almost everyone who has experience writing code, I’ve been guilty of doing a crappy commenting job. I write a piece of code and go back months or years later to realize that I have NO idea what I did and nor does anyone else. Thus, I am now at the opposite end of the spectrum. There’s a loop of some sort, there’s a comment explaining what it does. If there’s an equation I’m solving, the equation is in my comments. If I pulled material, such as an algorithm from a book, information on the book, including the page numbers involved, are added to my code.
Seriously.
As you may guess, I now hold everyone to those standards…and their code almost never holds up. However, there are different levels of crappy code. Specifically, there are three of them.
The least offensive level of crappy code is that which is reasonably well-commented but has stupid variable names like Fred, Wilma, Betty, and Barney, i.e. names that have no bearing on what the variable actually does. I almost never see this.
The second level omits these useless variable names, choosing instead to use names that actually relate to their functions. However, comments are sparse, at best. If you have good familiarity with the algorithm, there’s a chance you might understand it…maybe. This is actually most of what I see.
The third and most egregiously awful level combines both of the worst aspects of the coding errors mentioned above: no commenting and nonsensical variable names. When you ask the person how other people are supposed to keep track of their code, you’re told you simply need to know how it works. I’m not normally a violent person, but it is infuriorating enough to make me want to throw my favorite software engineering text at them.
So please – if you’re writing code, please do an adequate job of coding AND use appropriate variable names. I’m too short on books to lose too many.
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.