🔒 Locked

Commenting Styles

Started by zackriggle May 18, 2003 at 12:52 PM 5 replies 400+ views

Original Post

May 18, 2003 at 12:52 PM

I am just curious as to how everyone comments their code... I do mine like this:

  

//================= CLASS ===================

//                 CLASS X

//===========================================

 class X
 {
 public:
    /*
     *  Functions
     */
     void DoSomething();

    /*
     *  Variables
     */ 
     int Something;
 }

/*@@@@@@@@@@@@@ FUNCTION @@@@@@@@@@@@@@*
 *             DoSomething             *
 *@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@*/
 void X::DoSomething
{
  // Initailiza our vars...

  char* z;
  z = new char[125]; // We need a 125-byte buffer


  //Clean up

  delete[] z; // z was a char* that we used as a buffer

}

ApochPiQ

May 18, 2003 at 12:59 PM

"Comment"? What is this "comment"?

Actually I usually have a big nasty disclaimer and such at the top of each file, plus a quick header about each function/class/member''s behavior.

  //

// CoreMUSE® Initiative

// Copyright © 2003-2004 PiQ Software, LLC.

// All rights reserved.

//

// Use of any portion of the CoreMUSE® source code is subject

// to applicable agreements which can be found elsewhere. Any

// violation of said agreements is a breach of copyright law,

// and will be met with appropriate legal action.

//

// COREMUSE.CPP code file

// Program entry point and parameter processing code

//



// Header files

#include "common.h"

// Internal function prototypes

void ParseParameters(CString &Parameters);
void DisplayStartupHeader(void);


//

// MAIN()

// Program entry point

//

// This function scans the incoming command line arguments and

// decides what action to take based on the input. 

//

int main()
{
	// Initialize MFC

	if(!AfxWinInit(GetModuleHandle(NULL), NULL, GetCommandLine(), 0))
	{
		cout << "Failed to initialize MFC. Server cannot start." << endl;
		return 1;
	}

	// Variables

	// These should be listed after the MFC initialization

	// to prevent page faults if MFC is not present.

	CString Parameters;
	CString SingleParam;
	int Position;

johnnie2

May 18, 2003 at 1:02 PM

I suppose I''m a little less clear in places and a little more descriptive in places; I usually have very few comments in a class declaration, and, if a function is particularly important, a small description in that function''s header. My version of that source would be:

  
class X {
   public:
      int Something;

      void DoSomething();
};


//==============================================================

//

// X::DoSomething()

//

// Does something.

//

//==============================================================


void X::DoSomething() {
   char *z;

   z = new char[125];   // need a 125-byte buffer because <insert reason here>


   delete [] z;
}

________________________________________________
RapscallionGL development continues...
"Optimal decisions, once made, do not need to be changed." - Robert Sedgewick, Algorithms in C

Way Walker

May 18, 2003 at 1:07 PM

When working by myself, I don''t comment much. I use long names for functions, variables, and the like. This tends to make the code self-explanatory. I also try to go with the simplest implementation possible so, if I have forgotten what was happening, it''ll take me just a couple seconds to figure it out. When I do something more complex (for speed or whatever) I comment a lot more, trying to give a clear explanation in English of what''s happening.

When working with a group, I just use whatever the group decides on for its commenting conventions.

Zipster

May 18, 2003 at 1:10 PM

This is a bad place to say you don't comment much

You're flopping around like an injured seal in the middle of the ocean here!

I comment when my intentions aren't clear. For example, if I'm opening a file, I don't comment /* Here I am opening a file*/, but if I'm parsing in it a certain way, that gets documented. Et cetera.

[edited by - Zipster on May 18, 2003 2:11:10 PM]

Way Walker

May 18, 2003 at 1:29 PM

quote:
Original post by Zipster
This is a bad place to say you don''t comment much You''re flopping around like an injured seal in the middle of the ocean here!

I comment when my intentions aren''t clear. For example, if I''m opening a file, I don''t comment /* Here I am opening a file*/, but if I''m parsing in it a certain way, that gets documented. Et cetera.

That''s what I meant, basically. As much as possible I try to make my intentions clear so that any comment would seem like /* Here I am opening a file */ and usually just comment when it''s not obvious from the code.

The KISS principle goes a long way to removing the need for comments.

And like I said, when I''m in a group, I do comment more.

Sneftel

May 18, 2003 at 1:30 PM

There was another thread about this a few weeks ago.

This is how I comment.

How appropriate. You fight like a cow.

[edited by - sneftel on May 18, 2003 2:37:12 PM]

Topic Locked

This topic has been locked by a moderator. New replies are not allowed.