I...just...can't...type...COMMENTS!!!

Anikom15 · 2010-03-07 03:21:48

I can't do comments, there's just something wrong with me. I don't document anything unless I force myself, and even then it's not a good comment. Why can't I comment well. Are there tutorials that can help with my commenting? Does anyone else have this problem?

fflarex · 2010-03-07 03:24:31

Comments kinda came natural to me, dunno how to help you there. My problem is coming up with reasonable names for functions and variables. I usually just use really bad function/variable names and make up for it with more comments...

Peasantoid · 2010-03-07 03:30:29

Well, what are you commenting? If it's simple code, you likely only need comments if it's doing something non-obvious.

Anikom15 · 2010-03-07 03:39:02

Well when sometimes when I look back at my code I can't figure out what the heck it's doing. I can't even understand my own code! That's how "non-obvious" it is and that's why I need to learn how to comment.

Peasantoid · 2010-03-07 03:47:22

You'd think being able to understand your code is incentive enough.
I can't offer any specific advice because I'm one of those people it seems to come naturally to, unfortunately.
It helps to not get into 'coding frenzies', where you write massive volumes of code but can't be bothered with the distraction of commenting.
Also, don't code while tired. It doesn't work.

Anikom15 · 2010-03-07 03:50:43

Ahh, I am indeed affected by coding frenzies, other symptoms include fits of rage when I get errors and an increase in typing speed.

Peasantoid · 2010-03-07 03:52:21

Okay. Typing fast generally causes errors. Before starting to code, calm yourself down - take a few deep breaths, eat a bun, whatever. Get yourself comfortable.

Also, test often. Very important. If you write something remotely complex, test it.

What language are you using? Techniques tend to vary between.

Last edited by Peasantoid (2010-03-07 03:53:10)

Anikom15 · 2010-03-07 04:00:08

Mostly python, but sometimes C and when I code C I always forget parentheses and semicolons and that jazz, probably cuz I'm used to the terseness of python, and ironically I tend to write more and better comments in C than in python.

Peasantoid · 2010-03-07 04:01:23

Anikom15 wrote:

Mostly python, but sometimes C and when I code C I always forget parentheses and semicolons and that jazz, probably cuz I'm used to the terseness of python, and ironically I tend to write more and better comments in C than in python.

Well it's just so easy to write Python. With C, the increased challenge causes even the most careless coder to think 'wow, wtf does that do? better comment it'.

.:B:. · 2010-03-07 07:29:19

/* Commenting isn't that difficult,
now is it? */

bgalakazam · 2010-03-07 07:33:42

I like to comment things a lot, since looking back at them even a day later, they seem weird. For sections of code I really like:

// ========== foobar begin ==========
CODE
CODE
........
CODE
// ========== foobar end ==========

Last edited by bgalakazam (2010-03-07 07:33:56)

bernarcher · 2010-03-07 08:32:25

Anikom15 wrote:

I don't document anything unless I force myself, and even then it's not a good comment.

Most of us need to force themselves to comment a section of code which initially - while hacking it down - seemed quite logical and intuitive. When I started coding I had to establish a habit to do so as well.

Basically you must mentally train yourself to not leave a section of work whithout going back to the beginning and putting a few words about its use, tricks you needed, etc. It need not be a "good comment" (unless you were trying to distribute your code) but it should serve enough as a reminder.

It took a while to become a habit. But now this became thus natural to me that uncommented code just feels wrong - I have to write add few commenting words about it ...

pauldonnelly · 2010-03-07 09:42:21

Anikom15 wrote:

Well when sometimes when I look back at my code I can't figure out what the heck it's doing. I can't even understand my own code! That's how "non-obvious" it is and that's why I need to learn how to comment.

Could it be that your code is too scrambled to be easily documented? When you're writing, try pausing every few lines to think about whether what you just wrote is going to be clear later. If the answer is no, restructure it so that it will be. And if you think you'll need an extra hint after that, put in comments. The trick to writing comments is not to be so specific that a tweak to the program will invalidate the comment—the code is supposed to be your specific description. The meanings of variable names or complicated expressions are good candidates for comments (although a complicated expression can often be put into a function and given a name that way, skipping the comment).

Trent · 2010-03-07 14:08:22

My commenting style is to comment data structure and subroutine definitions, and only comment the actual code if it involves deep magic. I go by the rule that if a sub is hard to understand without line-by-line comments, it's too long and should be broken up into smaller pieces, which can then be documented on their own.

Are you using Python's docstrings? I use POD with Perl but I haven't written any Python in a while. Doxygen looks like a good doc system for C.

rson451 · 2010-03-07 16:20:38

No comments is way better than incorrect comments. If you do get in the habit of commenting properly, be sure to also get in the habit of updating comments if you update code.

Yannick_LM · 2010-03-07 18:08:33

Easy: start to write comments before code.

If foo is a complicated function with three arguments, start by writing this:

def foo(a, b, c):
    """Does this and that

     a: ...
     b: ...
     c: ...
 
     1./ First do this
   
     2./ Then that

     3./ And then finish.
     """


     # 1/ This


     # 2/ That


     # 3/ Finish

and then fill the blanks

This works specially well if you think about something on the evening but don't have something working quick.
You can write the comments now, re-open this code tomorrow and start hacking.

Bralkein · 2010-03-07 19:17:57

Yes, I think writing comments before code is a good idea. If you can't describe properly what the code is supposed to be doing, then it could well be that you don't completely understand the task.

I think that commenting dynamically-typed languages like Python is especially important. With static typing, you can often figure out what a method does by looking at the return type and the argument types. With Python, Ruby etc. a lot of this information is missing, so it's more important to describe what the method is for, what you should be passing in, what it returns and all the rest.

Once you get in the habit of commenting, you will just end up doing it automatically as a normal part of writing the code. It's a great feeling to stumble upon some old code, expect to have a really tough time working with it, but then you discover that you commented it thoroughly and it's very easy to understand

tavianator · 2010-03-07 19:23:12

Honestly the one thing that got me in the habit of writing comments was writing a serious project in assembly. Assembly is good for that because if you don't comment something complicated, then in two seconds you'll forget what it does, rather than in two days or weeks.

Anikom15 · 2010-03-07 20:40:35

Thx, the commenting before writing sounds like a good idea.

cmtptr · 2010-03-07 22:18:24

tavianator wrote:

Honestly the one thing that got me in the habit of writing comments was writing a serious project in assembly. Assembly is good for that because if you don't comment something complicated, then in two seconds you'll forget what it does, rather than in two days or weeks.

Kind of true. While commenting is definitely necessary in assembly, I found that once I work with assembly enough to used to it and then move up to something like C everything appears so readable that I get lazy with the comments.

Kiwi · 2010-03-08 01:52:32

What is a comment?

Ghost1227 · 2010-03-08 05:03:47

That obviously wasn't one...

Blue Peppers · 2010-03-08 08:32:12

My problem is that comments from 3am are usualy a gramatical nightmare, or unrelated to the code.

the_isz · 2010-03-08 09:26:20

Blue Peppers wrote:

My problem is that comments from 3am are usualy a gramatical nightmare, or unrelated to the code.

Lol, I can imagine...

The same code written at different times:

7pm:

for (int i=0; i<n; ++i)

10pm:

// a nice, friendly for-loop
for (int i=0; i<n; ++i)

12pm:

// a nice, friendly for-loop... maybe I should get some coffee?
for (int i=0; i<n; ++i)

2am:

// coffee coffee coffee coffee coffee coffee coffee
for (int i=0; i<n; ++i)

4am:

// maybr i shuldg et some sleepzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
for (int i=0; i<n; ++i)

bernarcher · 2010-03-08 20:01:44

On the other hand, even at 10 pm this was no useful comment. Everybody can see it's a loop. The comment should list the purpose of such a construct and what the variables ar meant for. Something like:

// Fetches some coffee on each iteration.
// n has to reflect the working hour when calling this
// (the later the higher).
for (int i=0; i<n; ++i)

Arch Linux

#1 2010-03-07 03:21:48

I...just...can't...type...COMMENTS!!!

#2 2010-03-07 03:24:31

Re: I...just...can't...type...COMMENTS!!!

#3 2010-03-07 03:30:29

Re: I...just...can't...type...COMMENTS!!!

#4 2010-03-07 03:39:02

Re: I...just...can't...type...COMMENTS!!!

#5 2010-03-07 03:47:22

Re: I...just...can't...type...COMMENTS!!!

#6 2010-03-07 03:50:43

Re: I...just...can't...type...COMMENTS!!!

#7 2010-03-07 03:52:21

Re: I...just...can't...type...COMMENTS!!!

#8 2010-03-07 04:00:08

Re: I...just...can't...type...COMMENTS!!!

#9 2010-03-07 04:01:23

Re: I...just...can't...type...COMMENTS!!!

#10 2010-03-07 07:29:19

Re: I...just...can't...type...COMMENTS!!!

#11 2010-03-07 07:33:42

Re: I...just...can't...type...COMMENTS!!!

#12 2010-03-07 08:32:25

Re: I...just...can't...type...COMMENTS!!!

#13 2010-03-07 09:42:21

Re: I...just...can't...type...COMMENTS!!!

#14 2010-03-07 14:08:22

Re: I...just...can't...type...COMMENTS!!!

#15 2010-03-07 16:20:38

Re: I...just...can't...type...COMMENTS!!!

#16 2010-03-07 18:08:33

Re: I...just...can't...type...COMMENTS!!!

#17 2010-03-07 19:17:57

Re: I...just...can't...type...COMMENTS!!!

#18 2010-03-07 19:23:12

Re: I...just...can't...type...COMMENTS!!!

#19 2010-03-07 20:40:35

Re: I...just...can't...type...COMMENTS!!!

#20 2010-03-07 22:18:24

Re: I...just...can't...type...COMMENTS!!!

#21 2010-03-08 01:52:32

Re: I...just...can't...type...COMMENTS!!!

#22 2010-03-08 05:03:47

Re: I...just...can't...type...COMMENTS!!!

#23 2010-03-08 08:32:12

Re: I...just...can't...type...COMMENTS!!!

#24 2010-03-08 09:26:20

Re: I...just...can't...type...COMMENTS!!!

#25 2010-03-08 20:01:44

Re: I...just...can't...type...COMMENTS!!!

Board footer