General programming conventions

[Etcher Squared Games]

So, I managed to get through my first game without any major problems.  Going back to it already I see that there are a few things I was I had done differently.

So, I did some searches and really found nothing on Design, standards, or conventions.

Plenty on tutorials, but nothing on a "best way how to" sorta thing.

And I'm sure the veterans here have come up with a way to do stuff.

So, have I missed such a webpage or perhaps we could just add to this thread a discussion about good general practices for current and future noobs.

(Please feel free to move this thread if beginners tech isn't quite the best place for this.  It seems like the best place to me at time of writing)

[Scummbuddy]

I hope this is a help. Just so you know, AGS is very loosely based on C programming, but is not the same. Some things, even as simple as commenting, are done differently, so don't look at the code below for word-for-word, but more as just a reference.Ã,  Some night when I don't have school the next morning, I'll trim this, or QuantumRich can, or anyone can post a reply with things to change.




C Coding Standards

General Comments
Every programming department has a some set of standards or conventions that programmers are expected to follow. The purpose of these standards is make programs readable and maintainable. After all, you may be the programmer who maintains your own code more than 6 months after having written the original. While no two programming departments standards/conventions may be the same, it is important that all members of the department follow the same standards. Neatness counts ! ! !


Naming Conventions
Use meaningful variable names ! !
For example, if your program needs a variable to represent the radius of a circle, call it 'radius', NOT 'r' and NOT 'rad'. The use of single letter variables is forbidden, except as simple 'for' loop indices.
The use of obvious, common, meaningful abbreviations is permitted. For example, 'number' can be abbreviated as 'num' as in 'numStudents'.
Begin variable names with lowercase letters
Begin function names with uppercase letters
Use all uppercase for symbolic constants (#define)
Use all uppercase for typedefs
Do not use global variables
Be consistent!
Separate "words" within identifiers with underscores or mixed upper and lowercase. Examples:
2-"word" variable name: grandTotal or grand_total
2-"word" function name: ProcessError or Process_Error
Use of Whitespace
The prudent use of whitespace (blank lines as well as space) goes a long way to making your program readable.

Use blank lines to separate major parts of a source file or function.
Separate declarations from executable statements with a blank line.
DO NOT use tabs (unless your editor changes TABs to 3 or 4 SPACEs). TABs may be interpreted differently by different editors.
Use 3 or 4 spaces for each level of indentation
Preprocessor directives, function prototypes, and headers of function definitions begin in column 1.
All statements in the body of a function are indented 3 or 4 spaces. Statements inside of a loop or part of an "if" structure are indented further.
Use spaces around all operators. For example, write x = y + 5;, NOT x=y+5;
Using the emacs or xemacs editor along with the the .emacs file provided for you will automatically indent your code appropriately.

Use of Braces
Always use braces to mark the beginning and end of a loop or "if" structure, even when not required.
See the indentation standard for appropriate placement of braces further down below.

Comments
Comments are the programmers main source of documentation. Comments for files, functions and code are described below.

File Header Comments
EVERY source file (.c and .h files) should contain an opening comment describing the contents of the file and other pertinent information. This "file header comment" MUST include the following information.

The file name
Your name
The date the file was created
A description of the contents of the file

For example
/*****************************************
** File:Ã,  Ã, proj1.c
** Author: Bob Smith
** Date:Ã,  Ã, 6/22/99
** E-mail: whomever@yourmama.com
**
**Ã,  Ã, This file contains the main driver program for project 1.
** This program reads the file specified as the first command line
** argument, counts the number of words, spaces, and characters and
** displays the results in the format specified in the project description
**
** Other files required are
**Ã,  Ã,  Ã,  1. chars.c -- routines that count each type of character
**Ã,  Ã,  Ã,  2. words.c -- routines that count each word
**Ã,  Ã,  Ã,  3. proj1.h -- prototypes for all functions needed by this file
**
***********************************************/


Function Header Comments
EACH FUNCTION must have a header comment includes the following:
function name
a description of what the function does
a description of the function's inputs
a description of the function's outputs
side effect of the function (if any -- this should be rare)
For example:
/************************************************
** CircleArea --
**Ã,  Ã, This function calculates the area of a circle
** with the specified radius
**Ã,  Ã, Inputs: the circle's radius as a parameter
**Ã,  Ã, Output: the circle's area as the return value
**************************************************/


In-Line Comments
"In-line" comments are used to clarify what your code does, NOT how it does it. Well structured code will be broken into logical sections that perform a simple task. Each of these sections of code (typically starting with an 'if' statement, or a loop or a 'switch' should be documented. A particularly important line of code should also be commented. Do not comment every line of code. Trivial comments (/** increment x **/) are worse than no comments at all.
An in-line comment appears above the code to which is applies and is indented to the same level as the code. For example:

Ã,  Ã,  /* check every element of the array */
Ã,  Ã,  for (i = 0; i < ARRAYSIZE; i++)
Ã,  Ã,  {
Ã,  Ã,  Ã,  Ã,  /* if it's odd, add one
Ã,  Ã,  Ã,  Ã,  ** if even, do nothing */
Ã,  Ã,  Ã,  Ã,  if (array % 2 == 1)
Ã,  Ã,  Ã,  Ã,  {
Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  array++;
Ã,  Ã,  Ã,  Ã,  }
Ã,  Ã,  }

Comments for #defines and variables
#defines may be commented on the same line as which they occur. Such comments should be aligned with the comments for other #defines. Once again -- Neatness Counts ! !
For example
#define NUMSTUDENTS 55Ã,  Ã,  /* number of students in the class */
#define NUMSECTIONS 12Ã,  Ã,  /* number of sections of CMSC201Ã,  Ã, */
#define NUMTASÃ,  Ã,  Ã,  Ã, 8Ã,  Ã,  /* number of graduate student TAsÃ,  */

variables may be commented in the same style as #defines
IF THEY ARE DEFINED ONE PER LINE as in the example below
Ã,  Ã,  int total;Ã,  Ã,  Ã,  Ã, /* total students this section */
Ã,  Ã,  FIlE *ifp;Ã,  Ã,  Ã,  Ã, /* input file pointerÃ,  Ã,  Ã,  Ã,  Ã,  */
Ã,  Ã,  double average;Ã,  /* class's final exam averageÃ,  */




C Programming - Indentation Styles

Code: ags

Choose one of the two styles and use it consistently
Ã,  Ã,  if (condition)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, if (condition) {
Ã,  Ã,  {Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  statement(s)
Ã,  Ã,  Ã,  Ã,  statement(s)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, }
Ã,  Ã,  }


Ã,  Ã,  if (condition)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, if (condition) {
Ã,  Ã,  {Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  statement(s)
Ã,  Ã,  Ã,  Ã,  statement(s)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, } else if (condition) {
Ã,  Ã,  }Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  statement(s)
Ã,  Ã,  else if (condition)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  } else {
Ã,  Ã,  {Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  statement(s)
Ã,  Ã,  Ã,  Ã,  statement(s)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, }
Ã,  Ã,  }
Ã,  Ã,  else
Ã,  Ã,  {
Ã,  Ã,  Ã,  Ã,  statement(s)
Ã,  Ã,  }


Ã,  Ã,  for (loop control expressions)Ã,  Ã, for (loop control expressions) {
Ã,  Ã,  {Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  statement(s)
Ã,  Ã,  Ã,  Ã,  statement(s)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, }
Ã,  Ã,  }


Ã,  Ã,  while (condition)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  while (condition) {
Ã,  Ã,  {Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  statement(s)
Ã,  Ã,  Ã,  Ã,  statement(s)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, }
Ã,  Ã,  }


Ã,  Ã,  doÃ,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, do {
Ã,  Ã,  {Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, statement(s)
Ã,  Ã,  Ã,  Ã,  statement(s)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, } while (condition);
Ã,  Ã,  } while (condition);


Ã,  Ã,  switch (integer expression)Ã,  Ã,  Ã,  switch (integer expression) {
Ã,  Ã,  {Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  case constant1:
Ã,  Ã,  Ã,  Ã,  case constant1:Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  statement(s)
Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  statement(s)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, case constant2:
Ã,  Ã,  Ã,  Ã,  case constant2:Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  statement(s)
Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  statement(s)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, default:
Ã,  Ã,  Ã,  Ã,  default:Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, statement(s)
Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  statement(s)Ã,  Ã,  Ã,  Ã,  Ã,  Ã,  Ã, }
Ã,  Ã,  }

This in no way came from my old C programming class...Ã, 

Once that this is fully changed to AGS style, we may add it to the AGS FAQ.

[Alynn]

Personally I use the Java programing conventions... but then again I'm a java programmer and I'm more comfortable with it... Since most of your projects will be solo, it really depends on your own style... coding conventions are there so multiple programmers can look at a piece of code and they can all add to it using the same conventions... and nobody will get confused....

Make up your own... use C's use Java... use whatever you want... unless you have a group of proggers... then you need to come up with one you all agree on...

[Etcher Squared Games]

Scripting aside, any AGS specific conventions?
Or scripting conventions that are AGS specific?

I was wanting coding pratices, but I was also looking into things like:

a good order to build the game
how to structure your game as you build it
etc etc...

[jetxl]

You mean a game design document?
Al Lowe has some examples on his website.
http://www.allowe.com/gamedesign/index.htm

I also make thumbnails of the rooms that are going to be in the game.
This help me remember things when I start making the actual backgrounds.

For the rest I try to make the game in a linear way. From begin of the gameÃ, to the ending. This makes it easier to test.

[Snarky]

For a more general (less programming-centric) idea of how to build an adventure game, The SCUMM Bar reprints some interviews with Ron Gilbert. He explains how Monkey Island was created, from the initial inspiration, writing the story, testing the gameplay and so on. His process sounds very solid (and is one I'm trying to follow).

Click on Monkey 1 in the sidebar, then select Magazine Clippings, and read the Ron Gilbert Interview 1 and 2 and the Edge article.