Code comments
-
How do you begin your code? Do you write comments at the beginning that tell who is the developer, the date, the name of the module?? I usually begin like this: ///////////////////////////// // fileName.cpp //Date: 09/04/2001 // Author: emanuele delbono // Version: 1.0 // Revision history // Date - Author // Comments: ////////////////////// And you?? Do you insert some sort of joke?? :-))
I just go in for the simple approach which easily identifies the files as one of ours...
/*------------------------------------------------------------------*/
/* Filename: Filename.cpp */
/* Desc: A quick description of the purpose of this file. */
/* */
/* Date: March 2002 */
/* Author(s): David Wulff */
/* */
/* This file is Copyright 2002 Battleaxe Software Limited, and may */
/* .. not be used or redistributed without license. */
/* */
/* License: http://www.battleaxesoftware.com/license/ */
/*------------------------------------------------------------------*/If there are any important revisions made to a file that deserve their own comments, this would be added as a normal comment block underneath the heading or with the appropriate section of code. However (and this one *is* a touchy subject with devlopers), we use comment blocks for each function...
/*------------------------------------------------------------------*/
/* processInput */
/* Process the input events. Called at each frame start. */
/*------------------------------------------------------------------*/We even use these with obvious things like constructors as it makes it easy to tell the tsrta of anew function when you are scrolling quickly through a large file. ________________ David Wulff http://www.davidwulff.co.uk Sonork ID: 100.9977 Dave …
-
How do you begin your code? Do you write comments at the beginning that tell who is the developer, the date, the name of the module?? I usually begin like this: ///////////////////////////// // fileName.cpp //Date: 09/04/2001 // Author: emanuele delbono // Version: 1.0 // Revision history // Date - Author // Comments: ////////////////////// And you?? Do you insert some sort of joke?? :-))
I use a VC++ add-in to generate .cpp/.h files. So every file has the same format that looks something like
#ifndef _REGISTRY_H_
#define _REGISTRY_H_
//****************************************************************************
//**
//** Registry.h
//**
//** Author : Todd Smith
//** Date : Mon Dec 10 10:21:58 2001
//** Notes : CMM lvl -1 compliant header
//**
//** $Id: Registry.h,v 1.5 2002/01/04 21:20:23 todd Exp $
//**
//****************************************************************************
//============================================================================
// INTERFACE REQUIRED HEADERS
//============================================================================Todd Smith CPUA 0x007 ... shaken not stirred
-
How do you begin your code? Do you write comments at the beginning that tell who is the developer, the date, the name of the module?? I usually begin like this: ///////////////////////////// // fileName.cpp //Date: 09/04/2001 // Author: emanuele delbono // Version: 1.0 // Revision history // Date - Author // Comments: ////////////////////// And you?? Do you insert some sort of joke?? :-))
It seems redundant to record the filename, author, date, version and revision history in the file itself when you are using a source control system. We don't have any kind of header on our source code, just #includes. Oh yeah we are ISO-9001 certified. Chris Hafey
-
Vimal Earnest wrote: in trivandrum Wow! A fellow Trivandrumite :-) Cool! Nish
My miniputt high is now 29 I do not think I can improve on that My temperament won't hold www.busterboy.org
Nish, I was just about to say, he would be working just a couple of blocks from your work place :-). Cheers Kannan
-
How do you begin your code? Do you write comments at the beginning that tell who is the developer, the date, the name of the module?? I usually begin like this: ///////////////////////////// // fileName.cpp //Date: 09/04/2001 // Author: emanuele delbono // Version: 1.0 // Revision history // Date - Author // Comments: ////////////////////// And you?? Do you insert some sort of joke?? :-))
Most our files start out with a header similar to what you have... except it's specially formatted to work with our version control system (PVCS) so that it automatically gets updated with the revision notes we type in. Functions usually have a couple lines explaining what they do (if not trivial), and what the parameters do (if not obvious.) For other blocks of code, I tend to comment WHY this code exists. That seems to be much more useful than just commenting WHAT the code does - that is often self-evident. For instance, you might find a comment like this: // Delete these registry entries becuase the API doesn't do it instead of // Delete HKEY_LOCAL_MACHINE/Software/App/Key :) Winning isn't everything, but then, losing is nothing.
-
How do you begin your code? Do you write comments at the beginning that tell who is the developer, the date, the name of the module?? I usually begin like this: ///////////////////////////// // fileName.cpp //Date: 09/04/2001 // Author: emanuele delbono // Version: 1.0 // Revision history // Date - Author // Comments: ////////////////////// And you?? Do you insert some sort of joke?? :-))
-
How do you begin your code? Do you write comments at the beginning that tell who is the developer, the date, the name of the module?? I usually begin like this: ///////////////////////////// // fileName.cpp //Date: 09/04/2001 // Author: emanuele delbono // Version: 1.0 // Revision history // Date - Author // Comments: ////////////////////// And you?? Do you insert some sort of joke?? :-))
I personally don't believe in comments like this. It's just one more thing to maintain and to quickly become meaningless when just one person in a long chain of developers forgets. To me commenting code like this is a bit like using writeln's to debug - it was useful in its day, but not the best way of doing things now. This sort of information is one of the things that version control software was created for. Cheers, Tom Archer Author, Inside C# Best mini-putt score = 22
-
How do you begin your code? Do you write comments at the beginning that tell who is the developer, the date, the name of the module?? I usually begin like this: ///////////////////////////// // fileName.cpp //Date: 09/04/2001 // Author: emanuele delbono // Version: 1.0 // Revision history // Date - Author // Comments: ////////////////////// And you?? Do you insert some sort of joke?? :-))
Yes, I have stuff like that. But I don't include anything that the source control system automates. Tim Smith I know what you're thinking punk, you're thinking did he spell check this document? Well, to tell you the truth I kinda forgot myself in all this excitement. But being this here's CodeProject, the most powerful forums in the world and would blow your head clean off, you've got to ask yourself one question, Do I feel lucky? Well do ya punk?
-
I use a VC++ add-in to generate .cpp/.h files. So every file has the same format that looks something like
#ifndef _REGISTRY_H_
#define _REGISTRY_H_
//****************************************************************************
//**
//** Registry.h
//**
//** Author : Todd Smith
//** Date : Mon Dec 10 10:21:58 2001
//** Notes : CMM lvl -1 compliant header
//**
//** $Id: Registry.h,v 1.5 2002/01/04 21:20:23 todd Exp $
//**
//****************************************************************************
//============================================================================
// INTERFACE REQUIRED HEADERS
//============================================================================Todd Smith CPUA 0x007 ... shaken not stirred
Todd Smith wrote: I use a VC++ add-in to generate .cpp/.h files. Todd, what add-in is this and where can I get it? Michael Martin Australia mjm68@tpg.com.au "Don't belong. Never join. Think for yourself. Peace" - Victor Stone
-
Todd Smith wrote: I use a VC++ add-in to generate .cpp/.h files. Todd, what add-in is this and where can I get it? Michael Martin Australia mjm68@tpg.com.au "Don't belong. Never join. Think for yourself. Peace" - Victor Stone
I use a modified version of this generate a .h and .cpp in the project dir (I can send a copy if you like) http://www.codeguru.com/devstudio\_macros/make\_file\_pair.shtml And then a slightly modified version of this to paste blocks of code into a file (one or .h and one for .cpp) http://www.codeguru.com/devstudio\_macros/code\_template\_sandy.shtml Todd Smith CPUA 0x007 ... shaken not stirred
-
I use a modified version of this generate a .h and .cpp in the project dir (I can send a copy if you like) http://www.codeguru.com/devstudio\_macros/make\_file\_pair.shtml And then a slightly modified version of this to paste blocks of code into a file (one or .h and one for .cpp) http://www.codeguru.com/devstudio\_macros/code\_template\_sandy.shtml Todd Smith CPUA 0x007 ... shaken not stirred
Todd Smith wrote: I use a modified version of this generate a .h and .cpp in the project dir (I can send a copy if you like) That would be much appreciated Todd. Michael Martin Australia mjm68@tpg.com.au "Don't belong. Never join. Think for yourself. Peace" - Victor Stone