Guidelines for Code and Article Submissions
So, you're whiz-bang programmer and want to share your
knowledge with the world. Excellent! You've come to the
right place. CodeSampler.com has a world-wide audience and
there's no better way to test your mettle and prove yourself
than posting your code or article for all to see. You can
think of it as the ultimate peer-review process for honing
your skills and validating what you think you know.
User Submitted Code Samples
Subject Matter
As long as it’s some how related to game or graphics
programming, pretty much anything goes. And if you think
your subject matter is too much of a stretch to be game
related, think again. Game programmers use a wide variety of
tools, SDKs and libraries to design and develop games.
There’s more to game programming than DirectX and OpenGL. If
you’re a Qt expert, you could show us how to design GUIs for
tools like level editors and model viewers. A C++ expert
could share a useful design pattern, or a Python programmer
might show us how to automate a nightly test build for our
game projects. The possibilities are virtually limitless.
Project Size
To me, a good sample is small and straight to the point.
There shouldn’t be too much superfluous code standing in the
way of the main topic. For example, if the subject matter is
light-maps, you can easily convey the basics using a single
quad and two textures. It may be cool to create a sample
that loads an entire light-mapped game level as a
demonstration, but most newbies just want to understand the
basics of the concept and a huge sample tends to overwhelm
them with extras.
With that said, the key word here is, "minimalism". The
sample should cover a single subject or technique and use as
little code as possible doing it.
Of course, larger samples have their place to. If the
purpose of your sample is the actual loading of a
light-mapped game level, you should create a smaller sample
which isolates and demonstrates the light-map code
separately. This would help newbies tremendously in
understanding your larger sample.
Comments
Yes, have some.
But make sure the comments you write are useful... unlike
these:
// This is a
caps structure.
D3DCAPS9 d3dCaps;
// Get device caps.
g_pD3D->GetDeviceCaps(
D3DADAPTER_DEFAULT,
D3DDEVTYPE_HAL, &d3dCaps );
These are useless comments because the code itself is
self-commenting. Of course, if your sample actually deals
with using the D3DCAPS9 structure, comments are in order,
but make sure they’re useful and tell us things that are not
readily apparent. The following is more like it:
// Get the
device capabilities of the default device.
// NOTE: This is a heavy-handed method, so don’t call it
repeatedly during
// run-time. If you need access to this information often,
call it once and
// cache what you need.
D3DCAPS9 d3dCaps;
g_pD3D->GetDeviceCaps(
D3DADAPTER_DEFAULT,
D3DDEVTYPE_HAL, &d3dCaps );
You can also drop comments for blocks of code which are
common to all samples involving the target API, as long the
code is not directly related to understanding the sample's
subject. For example, if you write a code sample dealing
with some sort of bump-mapping, the user should be advanced
enough to know what these lines are for and we can skip the
comments.
glMatrixMode(
GL_PROJECTION );
glLoadIdentity();
gluPerspective( 45.0f, 640.0f /
480.0f, 0.1f, 100.0f );
In summary, write meaningful comments aimed at the sample’s
subject matter and place them where they have the most
meaning. I know that’s sort of vague, but writing good
comments is more of an art than a science.
Variable & Function Names
Variable and function names should be as self-commenting
as possible. Avoid short or cryptic names, which make use of
non-standard abbreviations.
I don't care what variable naming style you use, just
make sure you use it consistently through out your sample.
Here are the three major styles:
Underscore Notation:
int
some_loop_counter; // Every word
connected by an underscore.
Pascal Notation:
int
SomeLoopCounter; // No underscores.
Capital letters separate words.
Camel Notation:
int
someLoopCounter; // Same as Pascal,
but starts off in small cap
Also, since modern development IDEs such as Visual Studio
and eclipse support tool-tip style roll-overs for variables,
Hungarian notation is
not as useful as it once was and is therefore optional for
C++ samples, but please don’t use it at all in C# samples.
However, for C++, I still encourage the usage of prefixes such as g_,
s_, and m_ which designate scope:
int
g_nSomeGlobal;
static int s_nSomeStaticVar;
class someClass
{
public:
someClass() {}
int m_nSomeClassMemberVar;
}
Coding Style
Where, Oh where, should put my curly braces? Actually, I
don't care as long as your coding style is consistent
through out the sample. If you're flexible with your style
and you want your code to look more like an official
CodeSampler sample, just download a few and look them over.
Other than that, it's up to you.
My only real pet-peeve is long runs of code which has
been jammed together in giant monolithic blocks without any
white-space. It's really hard to read code like that because
it looks like a huge run-on sentence.
Global Variables
In commercial software globals are a no-no and should be
avoided whenever possible. However, I tend to use them quite
a bit in samples because they help to simplify the code
considerably. It also makes it very easy for newbies to
search for the usage of a certain variable, which is much
harder if the object In question is being passed around from
function to function as a pointer. In short, I have no
problem with globals as long as your sample doesn’t deal
specifically with an architectural issue of game or engine
design.
For example, if your sample deals with a particular shader
effect, feel free to use globals to setup your shader. Any
programmer worth his salt knows that you wouldn’t use
globals like that in a real life game engine. On the other
hand, if your sample deals with the architectural issues of
writing a state manager for a game engine, the usage of
globals might be confused as an important aspect of the
state manager’s design.
Error Checking
To keep the samples short and to the point, I typically
skip error checking unless it’s directly related to the
subject matter being covered. I leave this decision up to
you.
The only exception to this is full-screen samples that
mess with the desktop's resolution and color depth. I can't
stand it when a sample crashes and leaves my desktop stuck
in 640x480 - 16 bit color! Therefore, if you write a sample
that supports full-screen to windowed mode toggling, you
better make sure it can recover properly if an error is
detected or an exception is thrown. If you're not positive
how to do this, your best bet is stick with windowed mode
samples. I prefer them any way.
SDK & Library Usage
Most SDKs and libraries are too big to include in the
sample’s downloadable .zip file, so samples that use
third-party SDKs or libraries need to ship with a "readme.txt"
file or instructions on where to get the resources and how
to install it properly. Here's an example of a
"readme.txt" file from a
Python / C++ sample.
If your sample uses a SDK like DirectX or Cg, which has a
professional installer that registers environment variables
or auto configures Visual Studio's paths, you can skip the "readme.txt"
file. Just make sure your sample is configured correctly to
use these.
I also prefer that third party SDKs and libraries be
installed on the development system as specified by their
designers. Customizing the install of many SDKs and
libraries quickly leads to samples that only compile
correctly on your system.
Finally, if you sample is DirectX based and it uses the
D3DX utility libraries (DXUTMesh.h, DXUTsound.h... etc.),
please copy the required files into your project and include
them locally. These files are not officially part of the
DirectX SDK and often change when Microsoft release a new
version of DirectX. It's annoying to download a cool sample
only to find out you can't compile it with the newest SDK.
Samples should be completely self-contained with the only
exception being usage of the SDK's "official" headers and
libraries.
Build Settings
Samples aimed at the Windows platform need to ship with
Visual Studio 2003 .NET project files (.vcproj). Additional
support for the older Visual Studio 6.0 is optional (.dsp).
Samples aimed at Linux should ship with at least a GNU
Makefile, but I would prefer to see samples that ship with
both a GNU Makefile and eclipse project files.
If you don’t have access to Visual Studio 2003 .NET, or
you’re not familiar with eclipse, I can assist you by
creating these project files for you.
All builds should complete with 0 warnings and 0 errors and
please don’t use a #pragma to hide a warning unless it is
well commented as to why the warning can’t be removed.
Also, do not include any header or link to any library
that isn't actually required for compilation of the sample.
User Submitted Articles
Sorry. I haven't finished this section yet since I still
haven't decided how to handle articles, but of you have an
article to submit, go ahead and send it in and I'll use it
in my layout tests for the article pages.
Attack of the Space-Mutant, Zombie Lawyers!
Ok. It seems that I haven't scared you away yet with all
my anal retentive musings concerning sample and article
writing, so you must be really interested in submitting
something. If that's true, lets talk about legal matters.
Terms and Conditions
By submitting your code or article to "the Web Site" (www.CodeSampler.com),
you are granting the Web Site a permanent, non-exclusive
license to use the code or article in any format the Web
Site deems appropriate, with the assurance that you will
always be given full credit for your work, and that you will
retain full ownership of it.
If you agree to these Terms and Conditions and are still
interested in submitting your code samples or articles, you
may send your submissions to me using the following address:
Please make sure to give your email a descriptive subject
line written in English so I don't accidentally delete it as
spam. I'll try my best to acknowledge receipt of the code or
article within two days of receiving it.
I look forward to your submissions.
Kevin Harris
|
