Programming conventions

[+Gemintronic]

Here is what I'm currently using for my new homebrew:

 

' CONVENTIONS:  COMMANDS are in uppercase.  variables and constants in lowercase.
' Labels are capitalized.  Major comment sections are uppercased.  Game Maker style choices are used
' when appropriate.  Resources start with a lowercase type followed by an underscore and a capatilised
' name.

 

What do other people prefer?

[GroovyBee]

Its good to have a defined programming style as long as you are consistent with it. If you work for a large software house they'll have their own internal style guide for code layout. That makes peer reviews of source code "easier" because it all looks the same.

[+Gemintronic]

No particular style for you then GroovyBee?

[GroovyBee]

It spends on the language

[+Gemintronic]

It spends on the language

 

I'd guess you're mostly... C?

[GroovyBee]

I'd guess you're mostly... C?

 

Nope! C, C++, PERL and a boatload of different assembly languages.

[+Gemintronic]

Okay. So, no similarities in conventions because of language differences and company practices. What about comment descriptions for functions?

[GroovyBee]

What about comment descriptions for functions?

 

Again, it depends on the language . Assembly language functions tend to need more information in their function description than a high level language in my experience. Such information might include where parameters come from e.g. stack, registers or memory locations, what registers are used/trashed and what is in registers when the function completes. That way when you call the function you can see how it is set up, what registers you must save (if any) before the call and what register(s) you get a result in. For complex projects that information makes life much easier when you come back to things later.

[+nanochess]

I tend to write games in assembly language as I find compilers just too unoptimal.

 

So far my convention is to use uppercase for labels that are constants, lowercase separated by underscore for functions, local labels using only point and number, and assembly code in lowercase.

 

Functions separated, commented at start for args input/output and some info about operation.

 

Some comments at right for important points. And of course some comments on how some function works or what reason was behind its implementation.

 

Furthermore at the top of each source code module I like to put revision dates with comments of changes (great help to detect introduced bugs). And when a module becomes too big or it is platform independent I just separate it in something clearly named.

 

By example for Princess Quest I've a "nucleo.asm" (core) module used both by MSX "quest.asm" and Colecovision "questc.asm" versions where I put platform dependent code.

[SeaGtGruff]

I sometimes change my preferences from day to day, but in general I use all uppercase for register names (VSYNC, INTIM, etc.) and also for assembly opcodes (LDA, STX, etc.). I use all lowercase for batari Basic commands (if, then, for, next, etc.) and variable names (a, b, player0x, lives_remaining, etc.). And I generally (but don't always) use a mixture of uppercase and lowercase for line labels or routine names (Move_Player, Check_Collisions, etc.). But I don't stick with these conventions religiously, because it can be a hassle to have to remember whether some label was supposed to be all lowercase or a mixture of uppercase and lowercase. The only convention I stick to religiously is that register names and assembly opcodes are all uppercase.

 

Aside from that, I always put each program instruction on its own line, rather than squeezing a bunch of instructions onto the same line with colons-- unless there's some reason to put multiple instructions on the same line, such as when setting several variables to the same value (to help optimize the compiled code for space), or when the instructions are part of an if-then-else construct.

 

Also, I put spaces around mathematical symbols (a = b + c * d, not a=b+c*d), because otherwise I think the "mathematical sentence" istoohardtoread, since the individual parts don't stand out like separate words. Likewise, I space after the comma in a multi-dimensional array or list of parameters, such as a = my_usr_function (b, c, d).

 

I indent 3 spaces at a time when coding for the Atari. I think single-space indentation sucks, because the line labels don't stand out enough, and if nested indents are each indented a single space per nest level (um, am I coining new gibberish terms?), then I think the lines look sloppy when you glance at the code, as if the programmer couldn't be bothered to indent the same amount each time-- the different levels of nesting don't stand out enough. I think it takes at least 3 spaces for the line labels to stand out from the code lines, and since I do use nested indents in batari Basic where appropriate (such as in a for-next construct), I think more than 3 spaces per indent level starts to use up too much line space for the indents. That's really more of a bother in assembly programs, because I like to devote the right half of the line to a detailed cycle count (number of cycles for the instruction, total number of cycles since the beginning of the last horizontal blank, running color clock count (cycles times 3), current screen position (color clock count minus 68), and effective horizontal position (if I'm strobing a sprite's position register-- current screen position plus 4 or 5).

 

As for comments, it depends. If I'm writing a lengthy explanatory comment that consists of multiple sentences, then I write them as though I were writing sentences-- lowercase except at the beginning of a sentence or line label, or all uppercase for register names or opcodes, with a period to end each sentence. And I usually start the next sentence on the same line if possible, just as if writing normal text, except when I want to begin a new paragraph (yes, some of my comments are that long!), or when I'm including a bulleted list in a comment, etc. But if it's just a brief comment-- not even a complete sentence, just a quick aside-- then I usually type it in all lowercase (except when referencing register names or line labels) and omit any period at the end.

[gorf68]

I use uppercase assembly mnemonics for my homebrew stuff, apart from that I generally just follow the default rules at work...

 

I do tend to write all variable names as one string with no underlines or non-alphanumeric characters etc, you don’t get problems with these characters if you don’t use them! I tend so separate words within a longer variable name by capitalising the first letter of each word giving: aVariableNameLikeThis

Edited October 30, 2012 by gorf68