Sometimes when writing programs I forget to put in any comments at all. Then later I come back to the code and I'm like, "What the F is this shit?" Anyone else have this problem?
No. I always understand my code later.
i can usually figure it out again pretty quickly. however, i have a different problem where the comments i write seem OK when i write them, but they end up being practically useless for going back later or other people's reading. i think a lot of open source project coders have this problem as well :)
Yes, I too have the same bad habit. I hate myself for doing it...
On my next sizable project, I'm going to try to write the comments first, then write the code around them (amending the comments when necessary). Hopefully that'll work.
After having worked on alot of uncommented code (Written by someone else) and spending loads of time just figuring out what the hell some parts of the code were supposed to do (The original programmer was a big fan of global variables), I now comment more, like, too much...
the only thing i ever use comments for is placeholders for code i havent written yet... sorta like this...
sub proxy_check($)
{
my ($ip)=@_;
for my $port (PROXY_CHECK)
{
# needs to be implemented
# die sprintf S_PROXY,$port);
}
}Just consider yourselves lucky you don't have to code in APL. APL coders get two degrees in university: Computer Science and Mesopotamian Ideogram Studies. There's a language where all the comments in the universe won't help you.
I don't think anyone actually uses APL for anything, though.
>>9
Apparently the previous edition of my DiffEq book had applications in APL. :/
I understand that APL is used extensive by actuaries. How the language is suited to insurance work, I can't imagine.
>>11 is some sort of satire, but I don't get it.
No, >>11 makes sense. APL is an array programming language, so it even sorta makes sense that people who deal with numbers and numerical relations would use it. However, there are several languages improving on APL, such as A+, J, and K.
//This is a comment. I like comments.
Anyways, I've seen people commenting like this:
a = a + 1; //Increment ax = psmov2(*(int *)(fp[2]->varm),sizeof(struct tn)*3,0,0,0);return x; //Return x>>14
Well, of course! They just added the easy comments for starters, then intended to come back and comment that hard thing that they wrote but don't really understand.
You should comment every function. What each variable represents, the return value, and any errors/exceptions which might occur.
Other that that, comment only things that you find would make yourself laugh a few months from the time you write it.
You should also comment anywhere that you make an assumption (e.g. assuming little endian).
x = psmov2(*(int *)(fp[2]->varm),sizeof(struct tn)*3,0,0,0); #Assuming I'm hired for maintenance>>18
Uh, you shouldn't assume little endian at all.
assume all you like, but watch out for the tomahawks
oh wait, *e*ndian.
If you're going to write image-processing or other code which manipulates huge arrays of bytes, you'd better be assuming endianness and reading and writing 32-bit or larger values, or your code will be dog slow. There's no way around this. If it has to be portable, you'll probably have to write two different version for different endiannesses.
Of course, >>22, but then the routines in which you did this would obviously have the assumed endianness in their name, or the #ifdef that includes them, or something like that.
Another problem with comments is that most people don't comment regular expressions, yet they are always completely unreadable. It's not that uncommon to waste 3 minutes to figure out a simple regex when writing a comment would have taken 20 seconds.
>>23
I've often written code assuming endianness or a certain alignment , but commenting when I did. It is easy enough to go back later and clean it up for portability after you get it working if you take this approach.
>>24
"Some people, when confronted with a problem, think 'I know, I'll use regular expressions.' Now they have two problems."
-- jwz
>>26 I lol'd at this quote. Happened to me a few times, so to solve the 2nd problem, I thought, "Hey, I know, I'll use a visual regex editor!", then I had 3 problems.
You should know how to do anything you do with regex. You use regex because doing that by hand would be terribly annoying.
I consider regex to be a basic, most useful tool at your disposal. I recommend everyone to get fluent with them. Fluent as in, last night I was talking to pops about some product and I didn't remember the name, so I didn't hesitate to tell him what I knew with a regular expression which included a backreference.
>>28 is the developer of http://www.ex-parrot.com/~pdw/Mail-RFC822-Address.html
Use the Pseudo-code Programming Process and write the comments before you write the code :
http://codebetter.com/blogs/darrell.norton/archive/2004/10/14/28596.aspx
It really doesn't take more time, and I'm glad I switched to this practice.
>>30
Sounds like a fancy name for making a draft.
>>30
Sounds like a poor substitute for using a powerful language (e.g. Lisp).
(I'm >>30)
>>31
I can't argue with the fact that this is a fancy name for a very, very simple technique.
>>33
If you express the requirements as unit tests (which is a good practice IMHO), you don't go past the method level, do you ? (i.e. the finest thing you can control is see if a method's effects fits the requirements).
The PPP is basically writing a summary of what your method/routine will do, then write your code after the corresponding comment. Typically you'll get 1-10 lines of code per line of comment, sometimes more if the code is straightforward.
It goes more in-depth than what you would achieve by unit-testing (since it explains the inside of a method), and arguably it may be overkill, but if it's decided on your project that there is a need to comment, it has good points :
_ it ensures comments will be written
_ it ensures only useful comments are written, too - too often have I seen worthless comments such as "// increment i by one" - with the PPP, since you write a summary, if the code is simple you won't write much or at all
_ it is much less boring than writing the comments afterwards - going back and commenting all the code you wrote during the last 10 days is dull, dull, dull
Kids these days, they need to trick themselves into discipline.
If you have to comment things you wrote 10 days ago without PPP, then it's just a discipline problem, not a methodology problem. (And if you ever have to comment other people's code, what they need is a punch in the face, not a new coding paradigm)
I believe writing comments using as I understand PPP would prevent you from changing your mind and improving the implementation while you write it.
I could maybe lead to over-commenting, too. There are a lot of things you need to get clear in your head, and maybe on your draft, but that you really should express by using a self-explanatory idiom instead of a comment. By resorting to comments, you'd make it more difficult to read.
>Kids these days, they need to trick themselves into discipline.
Can't argue with that. I do need to trick myself, and writing the outline of my method first is the least boring way I found. I dislike writing comments just as I finish to code, and too often I find myself writing them at the end of the day, or every other day, in bulk. It may be a failure of my character, but hey, at least I try to compensate for it this way.
>I believe writing comments using as I understand PPP would prevent you from changing your mind and improving the implementation while you write it.
I'm just lousy at explaining, then. Comments are never good if they are at the level of implementation, and PPP comments are no exception : they should document the intent behind a portion of code.
As for improving the design as you go, I like to do most of my thinking beforehand, so it rarely happens to me. When it does happen, well, I update the comments as I go. I don't think anyone would go "ah, but I can't change this otherwise my comments won't be appropriate anymore !" when it's so quick to change a line of comment. And since you only write the outline of your code, most improvements won't affect your comments since they will be too low-level.
>There are a lot of things you need to get clear in your head, and maybe on your draft, but that you really should express by using a self-explanatory idiom instead of a comment.
You can use self-documenting code AND a small comment every ten lines or so to help scan through code more easily. Again, I'm not talking about commenting every line of code (that would make it unreadable), and I'm assuming you do want to comment - there are pros and cons, some may argue writing self-explanatory code makes comments redundant.
Descriptive naming helps. In algorithms I put a summary of each step in a comment, like
# 1. Read user input
# 2. Perform bounds checking
is this "literate programming" thing just another name for PPP?
>>37
That first comment is only helpful if you're using a language where reading input is more than one or two lines (which it might well be if you're writing C, etc).
The second comment would be more useful if you explained what bounds you're actually supposed to be checking. Let the comment say what the code is supposed to do -- if it then turns out to be doing something rather different in some edge case, you have an easy reference for the correct behaviour and can fix the code to match the comment. Without documentation of what the bounds actually are, next time you look at that bit of code the only thing you have to go on is what the code says -- and if the reason you're looking at the code is that it's doing something wrong, you're pretty much shit outta luck if you can't remember the actual bounds you were trying to check.
>>39
Nowadays with GUI's and increased functionality, data from user input usually has to be decoded, pulled apart and run through a filter. The most common example is reading an HTTP request.
Too much blabber makes the actual code harder to organize and scan through quickly. If you really need to be held by the hand then maybe you shouldn't be debugging someone else's code (this is where descriptive variable naming, etc helps).
No, writing your own HTTP code is what makes it harder to organise and scan through quickly. Unless your project is a HTTP library or a web server, there's no reason to parse HTTP by hand. Especially in a GUI application.
No, a request with parameters has to be parsed. Plus the data may be encoded or may correlate to information stored on a database
>>34
Your "write javadoc-equivalent first" technique fails at making sure the comments are maintained.
>>43
It naively assumes the comments themselves won't have bugs. (Hay if it doesn't show up in a debugger it's not a bug, right.)
It's an issue of philosophy. If you view code as something to be written, then let sit, your code will be buggy and your comments will suck. But if you come back and read your code -- and, in so doing, make improvements as you deem necessary -- then you tend to get quality, maintainable code with meaningful comments.
Just look at various open source projects for evidence of this. Most self-proclaimed "Linux developers" take the former approach, and their code is crap, whereas BSD-based operating systems tend to take the latter view (OpenBSD developers being the most vocal about it), and if you read their code, it really is a world of difference. And those OSes are usually much more stable.