RE: m_ notation & naming conventions

[The Great Apple]

I didn't want ot post in the "Mods in Progress" thread so as not to clutter it.

I had assumed m_ standed for memory. All of these variables seem to be read/wrote to save games, and used as global variables throughout the files.

Personally, I've been trying to stick to the firaxis naming conventions for simplicity, however, maybe we should use "n_" instead of "m_" so as to make our changes even more identifyable.

 

[Impaler[WrG]]

I have noticed many people like to use comments like this

//Beging changes

code that got changed...

//end changes

Often they include their name and the mod this change is part off, My tecnique is a bit different. So far I have been comenting like so

m_originalvaraiable
n_newvariable // new variable added NAME, DATE, MOD

Some function ()
{
originalcode
my-oneline-functioncall() // new function added NAME, DATE, MOD
originalcode
}

myfunction() // new function added NAME, DATE, MOD
{
all my code
}

Dose this look like a good method? I would when done with the mod list all the files that were altered, all the changes can then be found using basic find or diff tools.

 

[PeteT]

I had assumed m_ standed for memory.

No, "m_XXX" is used to indicate that this is a member of a class. Sometimes "g_XXX" is used to indicate a global variable (but not by Firaxis). OTOH, "gDLL" is evidently global.

 

[12monkeys]

No, "m_XXX" is used to indicate that this is a member of a class. Sometimes "g_XXX" is used to indicate a global variable (but not by Firaxis). OTOH, "gDLL" is evidently global.

In the company I'm working we do it like this :

In the file header we add a comment :

/*
<Change-No>, <Name>, <Date>, <Comment (-> Mod)>
*/

in the source itself, we only refer to the <change-no> :

/* <change-no> - begin */
// ...
// old code, if some
// ...
...
changed or added code
...
/* <change-no> - end */

on one line changes we also to it like this :

new line // <change-no>

In general I think we should keep the naming conventions for variables and functions as firaxis did. If we invent something new here it may be more confusing than helping. If some changed something we are able to identify it by the change comments.

 

[The Great Apple]

We really need a standard commenting convention before things start getting combined. I quite like 12monkeys' method... but then again I also quite like the method proposed by Chalid here. Maybe some way of combining them could be found?

 

[Impaler[WrG]]

Seems to me their are 3 main ways we change the code

1 - Single line additions such as function definitions on headers, new variables and function calls within existing functions.

2 - New function created from scratch, these ofcorse nessesitate type 1 changes as well

3 - Blocks of alteration in existing function, these may optionaly include calls to new functions but often will not

12monkeys can you clarify?
Are the change numbers just references to the Mod or are they counting off each change made in a mod, so for example

<Start MyMod Change #5>
...code...
<End MyMod Change #5>

new line <MyMod Change #6>

Perhapse evern <MyMod Change #6 of 8>

Type 1 should have a tag containing AUTHOR/DATE/MOD as a minimum
Type 2 should have an additional description at the start of the function
Type 3 should have start and stop tags, both tags should have A/D/M, descriptions should be here or with the type2 function calls depending on ware most of the new logic is implemented, I think the descriptions should always be placed as close to the code which is realy doing the heavy lifting.

MODS should be a logical grouping of the bare-minimum nessary to implement a single XML element, behavior or event. We should include a Text file with the dll which lists every Mod, Author and describes the mod and lists every file that the mod can be found on.

 

[12monkeys]

Seems to me their are 3 main ways we change the code

1 - Single line additions such as function definitions on headers, new variables and function calls within existing functions.

2 - New function created from scratch, these ofcorse nessesitate type 1 changes as well

3 - Blocks of alteration in existing function, these may optionaly include calls to new functions but often will not

Agree!

12monkeys can you clarify?
Are the change numbers just references to the Mod or are they counting off each change made in a mod, so for example

<Start MyMod Change #5>
...code...
<End MyMod Change #5>

new line <MyMod Change #6>

Perhapse evern <MyMod Change #6 of 8>

The change-no is just any unique identifier which refers to the remark in the header of the file. This reduces typing, because you don't have to repeat all this A/D/M stuff in each changed line. The unique identifier could be like this:

"12m.001.a"

where:

12m : 12monkeys
001 : mod number. THis mod number should be unique for each developer. Means I someone implements a mod "ABC" this mod gets the number "x". His mod "EFG" gets the number "y". Another developer gets a number 001 for his own mods. So together with the developer the mod number is unique!
a : refers to the subversion of the mod. where "a" is the initial version and anything else is a bug fix or an enhancement.

This allows to search very quickly for mod changes and allows also to identify bugfixes for people who wants to update external code.

In the header there is a simple table where you can enter the details of the changes (last on top!) :

change-no | author | date | remark
-----------------------------------------------------------------
12m.001.b | 12monkeys | 24.04.06 | bug fix for mod ABC in function LMN
12m.001.a | 12monkeys | 20.04.06 | implementation of mod ABC

This system has the advantage that you can very quick identify if a file has been touched/changed or not : you just have to look on the header. But this is not a must, if we have a good working CVS.

The disadvantage is (of course) that you cant indentify in the line where this change belongs to. You have to go to the header for more details.

Type 1 should have a tag containing AUTHOR/DATE/MOD as a minimum
Type 2 should have an additional description at the start of the function
Type 3 should have start and stop tags, both tags should have A/D/M, descriptions should be here or with the type2 function calls depending on ware most of the new logic is implemented, I think the descriptions should always be placed as close to the code which is realy doing the heavy lifting.

to Type 3 : Imporant tohing to add here is, that the original code should alsways be kept as a comment in case you change code!!! This alows other people to rate the changes and to do bugfixing (presupposed the old version did work.

Not sure if I understood you correct, so sorry when this is what you meant with "descriptions" : For me there is no big advantage of having the A/D/M stuff close to the changed code. Its more important to have some explaining comments why this change has been done.

MODS should be a logical grouping of the bare-minimum nessary to implement a single XML element, behavior or event. We should include a Text file with the dll which lists every Mod, Author and describes the mod and lists every file that the mod can be found on.

Fully agree!

However, change-remarks and commenting of software is both a kind of philosophy as well as naming conventions. I saw a lot of approaches the last years and each method has it advantages and disadvantages. We always find anybody doing something different than what ever we'll decide here, thats for sure.

 

[The Great Apple]

MODS should be a logical grouping of the bare-minimum nessary to implement a single XML element, behavior or event. We should include a Text file with the dll which lists every Mod, Author and describes the mod and lists every file that the mod can be found on.

Hmmm, so you mean that if I changed the way the AI works out how many defenders it needs for a city, and I change how the AI works out which cities should have what emphasis types they should have two separate identifiers within the file, right?

Sounds like quite a good idea. I'd probably post them together though, just to save time.

 

[Impaler[WrG]]

The change-no is just any unique identifier which refers to the remark in the header of the file. This reduces typing, because you don't have to repeat all this A/D/M stuff in each changed line. The unique identifier could be like this:

"12m.001.a"

where:

12m : 12monkeys
001 : mod number. THis mod number should be unique for each developer. Means I someone implements a mod "ABC" this mod gets the number "x". His mod "EFG" gets the number "y". Another developer gets a number 001 for his own mods. So together with the developer the mod number is unique!
a : refers to the subversion of the mod. where "a" is the initial version and anything else is a bug fix or an enhancement.

This allows to search very quickly for mod changes and allows also to identify bugfixes for people who wants to update external code.

In the header there is a simple table where you can enter the details of the changes (last on top!) :

change-no | author | date | remark
-----------------------------------------------------------------
12m.001.b | 12monkeys | 24.04.06 | bug fix for mod ABC in function LMN
12m.001.a | 12monkeys | 20.04.06 | implementation of mod ABC

This system has the advantage that you can very quick identify if a file has been touched/changed or not : you just have to look on the header. But this is not a must, if we have a good working CVS.

The disadvantage is (of course) that you cant indentify in the line where this change belongs to. You have to go to the header for more details.

I dont realy like the sound of that, it sounds rather cryptic all just to save a line of text that could be a rather easily pasted. The number is just a Substitution ciphers for Author/Modname, lets just put that information directly in the comment, I personaly would find that easier then having to use a number. The initial Mod would be v1.0 and bug fixes 1.?? as needed.

I do like the idea of a table that lists every mod, its author and the purpose of the Mod. But I dont see why that should be keept in the Header file, their are what 30+ header files how would you deside which one your Mod would go on (when their might be changes on several files), even worse someone would have to search every header to find it (CodeBlocks has a nice tool to search like this) but I would rather not be dependent on search tools (and if we commit to such dependency a nice table becomes moot). Rather I think we should keep a single master table in a regular text file, much simpler and easier to find/search through. From that table you can get the Mod name and run a search for its name. Mod authors should be responsible for appending an entry on the table for their Mod.

 

[SimCutie]

I dont realy like the sound of that, it sounds rather cryptic all just to save a line of text that could be a rather easily pasted.
.....[snip]
Rather I think we should keep a single master table in a regular text file, much simpler and easier to find/search through. From that table you can get the Mod name and run a search for its name. Mod authors should be responsible for appending an entry on the table for their Mod.

Yes, I agree that it is too cryptic. Documenting change to source code is job of source code version/configuration management tool like CVS/SVN. That is what the CVS is designed for. Let it do the work.
We may use CVS-managed single ChangeLog text file for that purpose.
Let's add just short descriptive comment on source code itself.
Please don't add comment to header file unless you made actual change to heade file itself ( like adding member varibale). Editing comment in header will confuse file dependancy checker and force whole source code to rebuild itself.

 

[The Great Apple]

Right.

Summing up.

People like different types of commenting, but we need to have a standard. From reading what everybody has posted, can I propose this.

1) Header - All mod changes are listed in one log file. This file contains the mod name (brief), the author name, the mod version, and the release date of the mod. People edit this changlog when updating files on the server.

2) Types of changes -
a) Single line changes:
Format:
<code> /* Mod Name | Author Name | Mod version of update | Comment (optional) | Date changed */

For example:

doAITalk(i); /* TalkingAI | TGA | v1.1 | Calls the talking function | 26/04/06 */

b) New functions:
Format:
/* Mod Name | Author Name | Mod version of update | Comment (optional) | Date changed */
<code>

For example:

/* TalkingAI | TGA | v1.1 | Works out what the AI says | 26/04/06 */
void doAITalk(int iTalkType)
{
    if (iTalkType == 1)
    {
        AISay("You fight like a dairy farmer");
    }
}

c) - Editted functions:
Format:
/* START -- Mod Name | Author Name | Mod version of update | Comment (optional) | Date changed */
<code>
/* END -- Mod Name | Author Name */

If code is being replaced, then it should be left commented out so that it can be easily reverted. This code should be within the change brackets so that it can be easily seen.

For example:

    <code>
/* START -- TalkingAI | TGA | v1.0 | Makes the AI say 'hi' if you are at war with him | 26/04/06 */
    if (bLandWar)
    {
        AISay("Hi");
    }
/* END -- TalkingAI | TGA */
    <code>

Personally I prefer editted code comments to be completely untabbed so that they can be spotted more easily when combining. I supose it doesn't really matter.

Unless there are any major objections or very small changes somebody wants can this be final please?

Oh, and don't attack me if my sytax is bad - it's late, and I have people talking about ethics in loud voices a couple of meters away.

 

[12monkeys]

Thats OK for me.

 

[SimCutie]

On marking change in source, I am using style like this.

//----- BEGIN BY  SIMCUTIE ---------------------------------------
#ifdef SIMCUTIE_WIDGET
      <modified-source>
#else
      <original-source>
#endif // SIMCUTIE_WIDGET
//------- END BY SIMCUTIE ----------------------------------------

It seems too complicated and cumbersome to me to record version number and date in each code block manulally. I guess that it will be quickly get out of sync and become obsolute. Forgetful people like me is not good at keeping track of all the change version/date correctly and faithfuly. And I don't think that the version number/date is much helpful in understanding / managing source code and worth the manual/human effort.
As I said before, let the tool like CVS to the such a accounting/clerkish work. Instead let's do CVS versioning/check-in more frequently. If we do versioning frequenly, the CVS log will have enough time resolution to resolve date of source line change.
The mod identifier (like "SIMCUTIE_WIDGET" or "TGA_TALKINGAI" ) can be used as handle or unit of feature to name group/set of changes. This mod identifier can be used in ChnageLog file to refer the specific mod or change.
I used hoizontal line ("-------------") to let the changed part look more distingtive to human eye.

In separate header file ( I named it "CvGameCoreDLLExt.h" which is, in turn, included by global "CvGameCoreDLL.h" header), there will be lines like this.

#ifndef NO_GAMECOREDLL_EXTENTION
#define SIMCUTIE                   // base extension
#define SIMCUTIE_WIDGET       // custom widget
#define SIMCUTIE_EVENTEXT    // event extenstion
....
#define TGA_TALKINGAI
....
#endif // NO_GAMECOREDLL_EXTENTION

If we define or undefine specific Mod identifier, the DLL will be compiled with or without the mod feature.

 

[The Great Apple]

On marking change in source, I am using style like this.

//----- BEGIN BY  SIMCUTIE ---------------------------------------
#ifdef SIMCUTIE_WIDGET
      <modified-source>
#else
      <original-source>
#endif // SIMCUTIE_WIDGET
//------- END BY SIMCUTIE ----------------------------------------

It seems too complicated and cumbersome to me to record version number and date in each code block manulally. I guess that it will be quickly get out of sync and become obsolute. Forgetful people like me is not good at keeping track of all the change version/date correctly and faithfuly. And I don't think that the version number/date is much helpful in understanding / managing source code and worth the manual/human effort.

It's not too much effort IMO you just have to remember the date and version number when you are edting, and you can probably just copy-paste this from somewhere else in the code, something I suspect you do with the BEGIN and END tags anyway.

The trouble is with BEGIN and END tags is they don't really give enough informatoin to the casual reader as to what they do, or how long they were made. The date becomes espcially useful if you are editting somebody else's code - code which is only a few days old might not be best for editing, as they might be still working on it themselves, but code a few months old will probably be quite safe to edit.

As I said before, let the tool like CVS to the such a accounting/clerkish work. Instead let's do CVS versioning/check-in more frequently. If we do versioning frequenly, the CVS log will have enough time resolution to resolve date of source line change.

I've never used CVS before, but from what I gather this sort of information is stored in a separate log outside of the code, right? Personally, I feel that this info should be kept inside the code as well, so that it can be seen easily while browsing through.

In separate header file ( I named it "CvGameCoreDLLExt.h" which is, in turn, included by global "CvGameCoreDLL.h" header), there will be lines like this.

#ifndef NO_GAMECOREDLL_EXTENTION
#define SIMCUTIE                   // base extension
#define SIMCUTIE_WIDGET       // custom widget
#define SIMCUTIE_EVENTEXT    // event extenstion
....
#define TGA_TALKINGAI
....
#endif // NO_GAMECOREDLL_EXTENTION

If we define or undefine specific Mod identifier, the DLL will be compiled with or without the mod feature.

As for the enabling/disabling, I seems to me that can be down to the modder, and can be easily entered later if the code is commented properly originally. I do like the idea of using CvGameCoreDLLExt.h myself though.

The reason I posted the above is because we really need some sort of standard way of commenting before it gets too late, and the whole code becomes a mess. The suggestions I posted, while not set in stone, seem to me to be the best compromise between everybody's opinions.