PDA

View Full Version : Percent of comments in your code?



ober
07-01-2004, 10:03 AM
How much commenting do you do?

For instance, I have a project I'm working on in VB right now that is about 4500 lines and when I look at the stats, it says 25% of that is commenting. Now granted, I don't comment too much inside my code, but I do like to throw in good explanations of what a function/procedure is for and what certain random numbers mean (other than constants).

Another thing that bumps up this number is an addon in the VB IDE that throws in 6 (name of creator, time/date of creation, name of procedure, and description + 2 seperator lines) lines minimum of comment block for each procedure that I decide to do error trapping on (most of them).

I guess I'm just wondering what kind of percentages you guys have.

jverkoey
07-01-2004, 10:10 AM
i probably put anywhere between 20-25% commenting in my code. I usually have a block comment at the top explaining the purpose of the file, version history and updates, and also contact info in case i release the code to anyone. I also usually put a block comment at the beginning of a function explaining the return types and correct example of using the function (if it's a complex one), but if it's a simple function, I don't tend to comment it that much.

One thing I like to do once a certain block of code gets insanely complex is to space it out quite a bit so that each "thought" in the code has its own distinct area, allowing me to easily distinguish the code from one part to another.

As for line to line commenting, the only time I'd ever do that is if I was writing the code for a beginner's tutorial or something, otherwise it's just overkill and starts making your code look messier and harder to read then before (unless you figure out a way to do it nicely, heh)

viaxd
07-01-2004, 10:10 AM
I don't do a lot of commenting, since most of the code i write is fairly simple and no one except me reads it :)

afreedboy
07-01-2004, 11:01 AM
I don't do a lot of commenting, since most of the code i write is fairly simple and no one except me reads it :)


me too. I am a beginner to programming. I don't need to write a lot of comments as my program is very simple. I have only four or five functions in my program.

Shakti
07-01-2004, 11:09 AM
me too. I am a beginner to programming. I don't need to write a lot of comments as my program is very simple. I have only four or five functions in my program.

I was thinking the same but now when I am working on a big (at least to me) project I regret that I didnt comment my early programs and got used to it. Now I am sitting here with 10-20 uncommented files and I need to comment them sooner or later if I want to understand what is happening if I come back after a longer period of not coding or if I want to release the code (most likely this will be the reason why I will comment the code).

gcn_zelda
07-01-2004, 12:07 PM
I often start a project and then stop working on it. Then I go back and work on the project again.

I have a horrible memory, and I'm too lazy to try and figure out what the code does, so I comment every line.

ober
07-01-2004, 12:48 PM
jverkoey, I put the 1-1 comment in there just for laughs... but I guess we do have those kinda people: *looks at gcn_zelda*

DavidP
07-01-2004, 12:50 PM
1-1 comments are absolutely necessary in Assembly code.

gcn_zelda
07-01-2004, 12:53 PM
jverkoey, I put the 1-1 comment in there just for laughs... but I guess we do have those kinda people: *looks at gcn_zelda*
*cowers*

Thantos
07-01-2004, 01:14 PM
1-1 comments are absolutely necessary in Assembly code.
Um no. you don't need a comment on every ret or or movl $0, %eax. These are simple enough instructions that the stand out by themselves

jim mcnamara
07-01-2004, 01:41 PM
Example:
12 modules each ~4000 lines of C, 1 main module with11000 lines of C - total comments 122000.

-- about two comments per line of code. Also, there is a complete change history at the top of every module, and I'm not counting in this exercise. These histories range from 300 to 2000 lines long. This is what you have to do in very large, very complex systems.

Zach L.
07-01-2004, 01:55 PM
I'd think it's useless to comment every line of assembly. It's clear enough what a single line does, but perhaps not what small blocks of code are there to do.

About the two comments per line of code and change histories... That seems a bit extreme to me. CVS seems to be a much more friendly way of doing that.

alphaoide
07-01-2004, 02:25 PM
Program documentation requirement for my courses is a lot like variables library, program & function headers. So most comments are in classes and their functions, my main program is usually already self documenting so it's clean.
That said, my comment to code ratio could be 60:40 (that's right, more comments than code)

sean
07-01-2004, 02:41 PM
I practically never comment. If I need to fix something I put a comment there, and I have a few lins of comment at the top to sort of "entitle" my code file, but when it's time to compile I remove all of this. I selected 5%.

Thantos
07-01-2004, 03:13 PM
I'm not a big commenter. I know I should comment a lot more then I do, I just don't. There is a point of too much commenting however. Comments should enchance and not obscure the code. When I do comment I prefer multiple lines at the beginning of a function or large block. Also I use variables that are fairly clear in their purposes ( except i but everyone knows i is used for interger counting ;) )

Prelude
07-01-2004, 07:37 PM
I comment rather sparsely. My coding style emphasizes clarity, so comments usually do more harm than good unless I'm explaining my reasoning behind some code and not it's mechanics.

nvoigt
07-02-2004, 12:24 AM
I put the 1-1 comment in there just for laughs... but I guess we do have those kinda people


I do comment on a 1 line of code 1 line of comment base. Not for every line, but it evens out at function/class level.

If you deleted all source from my code, you could still see the structure and recode it.

Those comments have saved me a lot of work and I never had to think twice about what a function does when I had to dig into a project 3 years later.

I don't think there can be "too much" comment. If anyone else is bothered by the amount, s/he can delete it. But if it's not enough, no one will be able to pull some explanations out of thin air 5 years later.

sand_man
07-02-2004, 12:46 AM
if i dont comment my own programs, big or small, then i almost always forget what im doing