Advertisement

Code Comments

Started by May 01, 2001 05:18 PM
29 comments, last by Shannon Barber 23 years, 9 months ago
There are numerous reasons to comment. Header like comments on that square function will show up in Visual Studios intellisence, so when you type in the function name it will give you a brief description of what the function actualy does. This helps in differentiating between many overloaded functions that may or may not do the same things based on the namespaces. Obviously square in this case means square a number but it could also be someone''s derrivation of the RECT structure in class form.

If no one ever sees your code except for you personaly I encourage you to avoid commenting. Put the code into a folder and come back in 2 years and try to figure out what the hell you were thinking when you made it. Especialy if your one of the programmers who gives their variables funny names like int foobar. Or char chode. You''ll have a bunch of useless code on your hands. Especialy if it''s something as extensive as a game.

As for those automatic comment generating utilities, those are even worse than not commenting at all. If the utility makes even one small mistake you''ve tricked the person reading the code which in most cases is yourself or those who know more than you and are smart enough to realize the mistake and how it was made.

Commenting is nessassary, they take up less time than trying to find a bug in your game, they are easy to write and never give you any compiler errors! In a world where you can write "Hello World" to the screen in over 50 diffrent ways why can''t people see that there is a need to comment? It explains what you did, and why you did them.

Joseph Fernald
Software Engineer
Red Storm Entertainment.
------------------------
The opinions expressed are that of the person posting
and not that of Red Storm Entertainment.
Joseph FernaldSoftware EngineerRed Storm Entertainment.------------------------The opinions expressed are that of the person postingand not that of Red Storm Entertainment.
Comments are suppose to describe the behavior or objective of a piece of code. Niether of which are apparent from the code itself - certainly not when there is a logical error (bug) in the code.

However, it''s ten times worse when the bug is in the comment.

Not commenting, or being overly protective of your code, in the interest of preserving your position makes you a liability (and not an asset) to the company you work for. It''s not as though you need to worry about finding a programming job in the current market.

Magmai Kai Holmlor
- The disgruntled & disillusioned
- The trade-off between price and quality does not exist in Japan. Rather, the idea that high quality brings on cost reduction is widely accepted.-- Tajima & Matsubara
Advertisement
here''s what I use for file comments:
  // ============================================================================// CLASS:        txCString// DESCRIPTION:  A Text String class designed for basic UNICODE text strings, //               and compatibility with ASCII character sets.// REQUIREMENTS: This class requires a previously defined typedef of type//               ''txchar'' which defines which type of character set to use.                 txILanguage, <iostream>// AUTHOR:       Ron Penton// DATE:         02-01-2001// ============================================================================// Revisions:// ----------------------------------------------------------------------------// 1.0          02-01-2001      22:40// Initial Version// ----------------------------------------------------------------------------// 1.1          03-06-2001      10:57// - Added UnicodeType enumeration.// - Removed character representation. All character handling will be done//   with internal structures now.// - Added reliance upon DKSILanguage class interface.// ----------------------------------------------------------------------------// 1.2          03-06-2001      15:51// - changed back to compile time character representation.// - removed UnicodeType enumeration.// ----------------------------------------------------------------------------// 1.3          03-06-2001      22:00// - changed class name to txCString to reflect new naming convention.// ----------------------------------------------------------------------------// 1.4          03-06-2001      22:49// - added preprocessor directives for figuring out txchar type.// ----------------------------------------------------------------------------// 1.5          03-07-2001      13:57// - removed preprocessor directives and placed them in separate file// - added titlecase() method// - added concatenate() method// - added assign() method// ----------------------------------------------------------------------------// 1.6          03-07-2001      16:32// - changed interface a little, all strings operate with one txILanguage at//   a time// - added setLanguage() method.// - added getLanguage() method.// - added newString() and deleteString() helper methods.// - added copyString() helper method.// ----------------------------------------------------------------------------// 1.7          03-08-2001      18:04// - removed + operator, due to reference and lost pointer problems.// - added second newString() method, which takes a pre made string.// ----------------------------------------------------------------------------// 1.8          03-11-2001      12:53// - added iostream extraction and insertion operators, only work with regular//   ASCII strings, extended UNICODE characters are truncated to 8 bits for//   ostream insertion. These operators are for basic demonstration use.// - re-added + operator, now that i know how to make it work.// ----------------------------------------------------------------------------  



Note how I made a log of all changes to the class, so that users can see what has changed since they''ve last seen the class. This is VERY VERY VERY important in multi-user groups.

Note also that the header lists all required classes/modules.

and here is a sample function header that I use:

  // ----------------------------------------------------------------------------//  Name:           txCString::resize()//  Description:    Resizes string to a new length.//                  If new length is lower, letters are cut off end.//                  If length is higher, extra letters are filled//                  with p_fill.//  Arguments:      - p_size: new size of the text//                  - p_fill: character to fill extra spaces with.//  Return Value:   None.// ----------------------------------------------------------------------------    void resize( int p_size, txchar p_fill );  


note how I explain exactly what the function does, what each of the arguments mean, and what it returns. This is so the user is not left guessing what the function does, and can easily use the function WITHOUT being required to look at the code.

Here is a sample header for a data member of a class that I use:
  // ----------------------------------------------------------------------------//  Name:           txCString::m_refCount//  Description:    pointer to an integer which contains the current reference//                  count for the string. This should be incremented whenever//                  a new string is allocated which uses this string''s contents//                  decremented when a string is changed or deleted, and//                  the reference count should be deleted when no more//                  references exist to this string. (*m_refCount == 0).// ----------------------------------------------------------------------------    int* m_refCount;  


explains explicitly what the variable does.

This example is more for maintinence of the class, since it is a protected member. The above two examples are more for the benefit of clients than modifiers of the class.

Comments inside the function declarations should only be used when explaining important or unclear parts of the code, and a general paragraph comment on a logical block of code is much better than a line by line synopsis.

  int txCString::compare( const txCString& p_string ) const{    int result;    int min = p_string.m_length < m_length ? p_string.m_length : m_length;    // compare the strings up until the smaller one reaches the end.    // if either of them differ, return the result.    for( int i = 0; i < min; i++ )    {        result = s_language->compare( m_string[ i ], p_string.m_string[ i ] );        if( result != 0 )            return result;    }    // if the algorithm, gets this far, then the strings are either equal, or    // one string may equal the front portion of the other. if the strings    // are of different length, the shorter one is considered less than the    // longer. if they are the same length, return 0.    if( m_length < p_string.m_length )        return -1;    if( m_length > p_string.m_length )        return 1;    return 0;}  



Good commenting is the best thing a programmer can do. Don''t let your laziness cause you to do extra work trying to figure out what the code does.

===============================================
Have I no control, is my soul not mine?
Am I not just man, destiny defined?
Never to be ruled, nor held to heel!
This is my signature. There are many like it, but this one is mine. My signature is my best friend. It is my life. I must master it as I must master my life. My signature, without me, is useless. Without my signature, I am useless.
Well you know how people say there are two things you should never bring up in a converstation? That is religion and politics. (If no one has ever told that to you then God help us all ) Well i think there should be one more thing added to this list that people should never bring up in a conversation. That is "should code be commented or not." As you can clearly see, it can get out of hand. What i mean by that is some people start to get personal which just gets the argument even more heated. Now im not saying you shouldnt EVER talk about it. Certainly you must so new programmers will know that you should comment.

Personally, i think every one should comment. Im not saying comment things that can be clearly understood such as x = x + 1 but a good amount of explanation about how a particular functon or section of code works is just fine. Trust me, it WILL help you later on when you look at the code again and it will make your co-workers and boss happy. People you should always try to keep on your good side if ya know what i mean. And no one can tell me that 10 years down the road they will still understand every line of code they have ever written like when they first wrote it. Nu uh. I dont think so.

Well theres my post-o-lovin' Thats enough for now.

-SirKnight

Edited by - SirKnight on May 2, 2001 8:21:45 PM
We had this war last year!

I never comment. I don''t read other peoples comments.
I just read the code. The code does what it does. The
comments can say anything.

This view upset a lot of people last year. But I still think
its true.

So to all those who shall flame my botty...




"I am a pitbull on the pantleg of opportunity."George W. Bush
Duh. Why don''t you just say bad comments are a waste of time instead of all comments are a waste of time?

Duh? Duh.
Advertisement


Tell me Duh. How do you know *when* the comments are bad?
How do you know if the people writing them have bothered to keep them updated? How do you know if they were even accurate in the first place. The best coders I''ve met can''t string two coherant words together.

The code does not lie.
"I am a pitbull on the pantleg of opportunity."George W. Bush
Apart from commenting for the sake of people (and myself) readin my code, I have another reason. Once I have written some code, I write comments which explain and then justify the code. Often it''s when I get to commenting my code I begin to realise mistakes and design flaws which I wouldn''t have realised if I hadn''t bothered to go through what the code does in English.
Simon PriceSi@VBgames.co.ukwww.VBgames.co.uk
quote:
Original post by Davaris
Tell me Duh. How do you know *when* the comments are bad?
How do you know if the people writing them have bothered to keep them updated? How do you know if they were even accurate in the first place.



Tell me Davaris, how do you know *when* variable and function names are misnamed? How do you know if the people writing them have bothered to keep them updated? How do you know if they were even accurate in the first place?

Just because comments can become out of date if a programmer doesn''t update them is not a good reason ditch them. If you believe it is, then I assume you name all of your functions and variables a1, a2, a3, since variable and function names can be abused just as much as comments.

quote:
Original post by Davaris
The code does not lie.



Nope, but code can lie about the programmers intent ... and without proper function names, variable names, and commenting how would you know what the code is supposed to do?


- Houdini

- Houdini
I think a lot of comments can be replaced by asserts. Stuff like "you have to pass a non NULL pointer to this function". This "comments" are also checked when you run the program, so, if they are wrong or outdated, they stop the program and you can fix them imediately.

This topic is closed to new replies.

Advertisement