Coding_conventions modified by Hugh Greene

Hugh Greene — Fri, 20 Jan 2023 12:13:29 -0000

I am not really picky about what your code looks like in terms of
indentation. Traditionally, I use two spaces for indentation, I do not
use braces unless required, and I place braces on their own unindented
lines unless the code in the braces is three lines or fewer, in which
case I put the opening brace after the if(), or other statement.
Everyone else does the exact opposite of this, so pick your own style
and you'll fit right in.

Types

What I am concerned about and have been seeing happen a lot, lately,
are function and variable type confusion. I'll be succinct, and use
bullet points.

Always use the type which requires the fewest casts in your
code. If your function needs a double, take double. If your
function needs a float, take float. If your function works for
either, Robert has created scalar types for you to choose from based
on system. For example, graphics floating point types should default
to gs_scalar. Look around the code; chances are, the correct
scalar type is used somewhere.
Never use var or variant. This is the rule. The exception to
this rule is, you may use variant when you need to accept either a
string or real type, and you may use var if you need tot accept an
array of such objects. If you need to accept an array of only reals
or only strings, go ahead and use var for now, as ENIGMA does not
yet have an array type.

Naming convention

Another point is naming convention. I am not the underscore-case nazi. I
don't care what you name your own variables. Our current convention is
snake_case for basically everything. This is violated on arbitrary
occasion without repercussion. However, we are running a user-friendly
API here, and in user space, functions are expected to use a
consistent convention.

This convention is, again, snake case, with functions partitioned using
C
namespaces.


`draw_`	This is where primarily 2-Dimensional, but also dimensionality-insensitive drawing functions go.
`d3d_`	This is where functions that specifically concern drawing in 3D go. Some of these functions are renamed versions of functions from `draw_`, offered for the convenience of users searching for functions.
`sound_`	This is where functions go which concern sound resources. There are functions to play sounds and stop sounds from playing by resource ID, but the idea is that functions here specifically concern tangible sound resources.
`audio_`	This is where all other manner of audio functions go, as related to working with channels and playing instances of sounds.
`display_`	This is where you will find functions concerning the entire desktop's display, which may contain many windows not related to your program.
`window_`	This is where you will find functions that concern the window, as managed by the window server, desktop environment, and generically, the window manager.
`screen_`	This is where you will find functions that concern your program's drawing screen; that is, the region inside the window to which your program renders.
`instance_`	These functions concern object instances in general. Finding instances, iterating instances, creating and destroying instances.
`collision_`	These functions concern testing for collisions with instances. They work with not only a position for instances, but also a physical shape. They do not, in general, incorporate dynamics.

This is not a comprehensive list, but a general list of namespaces which
seem to run together or are otherwise not obvious.

Recent changes to Coding_conventions

Coding_conventions modified by Hugh Greene

Types

Naming convention