Style: Capitalizing functions, methods and member variables

[Snarky]

There's one thing about AGS coding that I can never seem to get right: capitalization.

I like to be consistent, but I'm not sure what convention to follow. AFAIK, all AGS engine functions are capitalized, whether plain functions (Random(), QuitGame(), IsKeyPressed(), etc.) or methods inside structs (Dialog.Start(), Maths.Sin(), Character.Say(), etc.). However, the built-in function handlers (repeatedly_execute(), on_mouse_click(), game_start(), etc.) are lowercase, and object event handlers (stuff like btnOk_OnClick()or cBob_Look()) will be initial-lowercase when following the AGS object naming convention. Also, the function examples in the manual are lowercase.

Similarly, the member properties of the built-in structs (Character.Speaking, GUI.Height, Hotspot.Name) are all capitalized, with a few exceptions (Character.x/y/z, mouse.x/y, Character.scrname). In contrast, plain variables (player, guis[], etc.) and the members of the game struct (game.score,  game.text_align, game.show_single_dialog_option, etc.) are lowercase. The struct member property examples in the manual are all in lowercase.

So, there's not a whole lot of consistency on the AGS end.

I usually write regular functions in lowercase (e.g. updateCategoryTree(), getScreenGraphic()) and methods inside structs in uppercase (e.g. Avatar.ReadProfile(), TotalLipSync.AutoMapPhonemes()), but this can lead to some weird inconsistencies. For variable properties I've never been able to decide between uppercase or lowercase.

Any tips? How do you do it?

[Crimson Wizard]

Similarly, the member properties of the built-in structs (Character.Speaking, GUI.Height, Hotspot.Name) are all capitalized, with a few exceptions (Character.x/y/z, mouse.x/y, Character.scrname). In contrast, plain variables (player, guis[], etc.) and the members of the game struct (game.score,  game.text_align, game.show_single_dialog_option, etc.) are lowercase. The struct member property examples in the manual are all in lowercase.

I think that lowercase variables were introduced earlier, and later Chris Jones was adding properties with new naming style (camel-case). But some of the properties had to be left lowercase for backwards compatibility. (This is actually possible to solve today).

Anyway, regarding the general question, this problem is not specific to AGS, it is an inevitable issue you are getting if you are coding a program which uses several libraries, or code from different sources, each with its own naming convention.

Personally I prefer to just ignore inconsistencies in AGS and use a similar naming convention to what we were using in the engine, which I grew a habit for, because it is more or less compliant with latest AGS API additions.

1. Global functions, simple variables, structs are in camel-case.
2. Objects of struct type which may be present in multiple instances - similar to character, GUI etc objects in AGS, e.g. tbxCustomTextbox or something like that. This is just for compliance with how AGS calls objects by default. I also tried doing this in camelcase, like TbxMyTextbox, but for some reason it does not work well for me.
3. Public variables, any properties and methods of a struct are in camel-case.
4. Protected variables of a struct begin with underscore and lowercase letter, but continue camelcase. This is a habit coming from C++ and C#, where you do not usually add "this." when referencing class members, so this special naming serves to distinct local and member variables. In AGS you always have to write "this.variable", so that's not so important.
If I am working on shared project with other people I can also just use camelcase for protected variables.
5. Local variables and function arguments are all lowercase with underscores.
6. Macroses are all capital letters with underscores.

Example: http://www.adventuregamestudio.co.uk/forums/index.php?topic=28979.msg636568444#msg636568444

[Snarky]

Thanks, CW! You're right; with libraries/modules from different sources you can never get perfect consistency, and usually there will be bigger issues than capitalization anyway. Looking at the API for the 9Verbs module in this other thread, for example, I'm not crazy about the capitalization of the arguments (no indication of word boundaries, NPCfacesplayer starts with uppercase while the others are lowercase, etc.), but that's a piddling concern next to a couple of Character* variables named "charid":

Code: ags

int NPCGoToCharacter(Character*charidwhogoes, Character*charidtogoto, eDirection dir, bool NPCfacesplayer, int blocking);

Most of your style rules make a lot of sense to me. I've toyed with the idea of going uppercase for anything public (possibly not including plain variables), and using lowercase for variables and functions that are script-local (not exported) â€" using underscore for anything where there could possibly be a scope collision, which is more or less your system.

The only thing I don't quite agree with is this:

2. Objects of struct type which may be present in multiple instances - similar to character, GUI etc objects in AGS, e.g. tbxCustomTextbox or something like that. This is just for compliance with how AGS calls objects by default. I also tried doing this in camelcase, like TbxMyTextbox, but for some reason it does not work well for me.

I don't like using both a Hungarian-style prefix as well as appending it to the name: btnOk or okButton, but not btnOkButton, you know? Since AGS style is Hungarian, I try to stick to that (though I sometimes have a hard time remembering prefixes for all the different GUI Controls and switch to the other style.