And what about a tool like doxygen ?

It requires some discipline while commenting your code, and generates a documentation from your comments. And during your project, you get both commented code (at least what each classe and function does, not the internals), and a code documentation which makes explaining things easier.
( _ What''s this function for ?
_ RTFM. )

I agree with the " no comments is better than bad comments". But commenting correctly is a skill in itself

BTW, there''s a whole gamedev article on the subject of comments and documentation :
The Art of Code Documentation

quote:

---

Original post by KalvinB
If people can''t understand what''s going on then they either don''t know the language well enough (or are too lazy to think for a second) or my code is sloppy.

---

KalvinB, knowing the language has nothing to do with not needing comments. You don''t comment to explain what a line of code does, unless it''s a horrible hack. Commenting is used to tell what the next 10 lines of code does in 1 line of english.

Any competent programmer can read code, but if the code is, for instance, AI code, and the person isn''t well versed in AI (to use Big B''s example) then the code will mean nothing to them.


Magmai, relax... breath...

Better?


- Houdini

Whenever this subject is raised people start saying things like "I don''t need to comment because I can read code as fluently as English". These comments are ridiculous. I can read English fluently, but if I want to look something up in a reference book I don''t start reading from page one until I come across what I''m looking for. I use the contents, index, chapter titles and section headings to provide me with a concise summary of sections of the book without having to read them in full.

This is how comments should be treated. They summarise or aid the understanding of a section of code so that the programmer doesn''t have to read it and work out what it does. At some point you have to review a function to remind yourself how it works. It''s a lot quicker and easier to read a few lines of English than many lines of code.

If code was difficult to write,
it should be difficult for follow!

quote:

---

I can read my code as plainly as english

---

For the most part I agree. But the function and variables must be named sensibly, and their names must relate to what they are used for.

I resently had to try and decypher somebody elses' 100 line function did. The function used four local variables - i, ii, iii, iiii!!! Totally meaningless names!

quote:

---

x = x+1; //Add one to x

isn't just a waste of space they make the code even harder to read

---

Totally agree, if when you write this code, if you don't know that x = x+1 adds one to x you should not be programming at all.

Edited by - Beelzebub on May 2, 2001 11:38:09 AM

>>Apparently some of you haven''t been to a code review

Code reviews! That''s all we ever do here at Intel. Code reviews are also for sissies.

If you can''t read the code by itself, you either:
1. haven''t done enough programming
2. are stupid
3. are too junior and need to mind your own business

-M

some of you people would have me comment this function

int GetSquareOfX(int x) {  return x*x;} 

Here''s my comment... go back to school.

While I think that commenting code is good practice, going to far in commenting is just plain dumb.

THis is definitely going too far.

/********************************************Author : Dick Head*Company : Dick Inc*Purpose : calculate the square of the input*Returns : Square of the input, which is a double*Date : 19/may/2000*Copyright : (C) Copyright 2000 Dick Head*******************************************/double square(double num){ return num*num;}

I''m not kidding when I say that a friend of mine writes comments like that. *shudder*.

Buster ? Did your parents drop you down the stairs when you were a baby ? In that case I forgive you for being an asshole !

Personally I feel there is a place for comments, but that place is as an eye catcher. Comments should only say what you are doing and not how you are doing it. It shouldn''t say why you are doing it either. The place to say that is in the documentation and comments are not documentation. Viewing it like a book the individual statement is a sentence, a group of statements seperated by blank lines from other statements is a paragraph and the comments serve as sub-section titles, functions group sub-sections into sections, file group sections into chapters and the entire program is a book. Reading the comments in a program should give you about as much idea of the details of the program as reading the table of contents for a book.

Commenting is good, not that I do it or anything, but it''s still good...

---
No game will ever rule more than CBT!