Comments (45)

1 Name: #!/usr/bin/anon 2006-01-16 21:04 ID:MRVbbw2K

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?

2 Name: #!/usr/bin/anon 2006-01-16 22:40 ID:cnJyrJqV

No. I always understand my code later.

3 Name: #!/usr/bin/anon 2006-01-17 07:12 ID:YOnHV1EH

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 :)

4 Name: #!/usr/bin/anon 2006-01-17 23:39 ID:JaVG/MQb


Good one!

5 Name: Albright!LC/IWhc3yc 2006-01-18 12:20 ID:wjQw1EuD


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.

6 Name: #!/usr/bin/anon 2006-01-18 15:23 ID:HhMMR51n

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...

7 Name: #!/usr/bin/anon 2006-01-18 16:16 ID:lR4u/qQo

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);

8 Name: #!/usr/bin/anon 2006-01-19 17:15 ID:dyZ7E8F7

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.

9 Name: #!/usr/bin/anon 2006-01-19 21:29 ID:Heaven

I don't think anyone actually uses APL for anything, though.

10 Name: #!/usr/bin/anon 2006-01-20 04:34 ID:Heaven

Apparently the previous edition of my DiffEq book had applications in APL. :/

11 Name: #!/usr/bin/anon 2006-01-25 00:32 ID:ak7BlML+


I understand that APL is used extensive by actuaries. How the language is suited to insurance work, I can't imagine.

12 Name: #!/usr/bin/anon 2006-01-25 13:01 ID:Heaven

>>11 is some sort of satire, but I don't get it.

13 Name: #!/usr/bin/anon 2006-01-25 15:25 ID:MRVbbw2K

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.

14 Name: #!/usr/bin/anon 2006-02-07 00:07 ID:hn8q2AFv

//This is a comment. I like comments.

Anyways, I've seen people commenting like this:

a = a + 1; //Increment a
x = psmov2(*(int *)(fp[2]->varm),sizeof(struct tn)*3,0,0,0);
return x; //Return x

15 Name: #!/usr/bin/anon 2006-02-07 01:32 ID:Heaven

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.

16 Name: #!/usr/bin/anon 2006-02-07 04:47 ID:dL9/X/Yu

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.

17 Name: #!/usr/bin/anon 2006-02-07 13:54 ID:hn8q2AFv


18 Name: #!/usr/bin/anon 2006-02-07 17:22 ID:9t2sb1Gq

You should also comment anywhere that you make an assumption (e.g. assuming little endian).

19 Name: #!/usr/bin/anon 2006-02-08 01:25 ID:hn8q2AFv


x = psmov2(*(int *)(fp[2]->varm),sizeof(struct tn)*3,0,0,0); #Assuming I'm hired for maintenance

20 Name: #!/usr/bin/anon 2006-02-08 02:13 ID:MRVbbw2K

Uh, you shouldn't assume little endian at all.

21 Name: #!/usr/bin/anon 2006-02-08 11:02 ID:Heaven

assume all you like, but watch out for the tomahawks

oh wait, *e*ndian.

22 Name: !WAHa.06x36 2006-02-08 13:32 ID:mD09zc8l


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.

23 Name: #!/usr/bin/anon 2006-02-08 14:23 ID:Heaven

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.

24 Name: #!/usr/bin/anon 2006-02-08 15:26 ID:AL38G8up

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.

25 Name: #!/usr/bin/anon 2006-02-09 01:47 ID:9t2sb1Gq

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.

26 Name: #!/usr/bin/anon 2006-02-09 15:58 ID:MRVbbw2K

"Some people, when confronted with a problem, think 'I know, I'll use regular expressions.' Now they have two problems."
-- jwz

27 Name: #!/usr/bin/anon 2006-02-10 00:35 ID:Heaven

>>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.

28 Name: #!/usr/bin/anon 2006-02-10 22:54 ID:hn8q2AFv

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.

29 Name: #!/usr/bin/anon 2006-02-11 14:05 ID:gSSyIXSb

30 Name: #!/usr/bin/anon 2006-02-11 14:46 ID:haVlcBYk

Use the Pseudo-code Programming Process and write the comments before you write the code :

It really doesn't take more time, and I'm glad I switched to this practice.

31 Name: #!/usr/bin/anon 2006-02-11 16:30 ID:WkPNJTJc

Sounds like a fancy name for making a draft.

32 Name: #!/usr/bin/anon 2006-02-11 17:34 ID:MRVbbw2K

Sounds like a poor substitute for using a powerful language (e.g. Lisp).

33 Name: #!/usr/bin/anon 2006-02-11 18:15 ID:X/TsMzv4

Sounds like a good attempt at plugging your pet language.

Also, couldn't >>30 be done by expressing the requirements as unit tests? Doing this can help you understand what you want to do and is more productive.

34 Name: #!/usr/bin/anon 2006-02-11 20:58 ID:haVlcBYk

(I'm >>30)

I can't argue with the fact that this is a fancy name for a very, very simple technique.

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

35 Name: #!/usr/bin/anon 2006-02-12 01:36 ID:SPkhzygq

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.

36 Name: #!/usr/bin/anon 2006-02-12 10:46 ID:haVlcBYk

>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.

37 Name: #!/usr/bin/anonymous : 2006-05-25 14:49 ID:Q6PuQxEv

Descriptive naming helps. In algorithms I put a summary of each step in a comment, like

# 1. Read user input

# 2. Perform bounds checking

38 Name: #!/usr/bin/anonymous : 2006-05-25 16:39 ID:VKOT/gMv

is this "literate programming" thing just another name for PPP?

39 Name: #!/usr/bin/anonymous : 2006-05-26 09:12 ID:Heaven

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.

40 Name: #!/usr/bin/anonymous : 2006-05-27 02:56 ID:24bl/jKL

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).

41 Name: #!/usr/bin/anonymous : 2006-05-27 04:24 ID:Heaven

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.

42 Name: #!/usr/bin/anonymous : 2006-05-27 14:08 ID:fuW+ylrf

No, a request with parameters has to be parsed. Plus the data may be encoded or may correlate to information stored on a database

43 Name: #!/usr/bin/anonymous : 2006-06-17 13:54 ID:6Y6HY38F

Your "write javadoc-equivalent first" technique fails at making sure the comments are maintained.

44 Name: #!/usr/bin/anonymous : 2006-06-18 00:22 ID:Heaven

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.)

45 Name: #!/usr/bin/anonymous : 2006-06-18 20:14 ID:puQ0Ofsk

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.

This thread has been closed. You cannot post in this thread any longer.