What're YOUR Naming/Commenting Conventions?

[anonymous1337]

My Naming Conventions - Java/anonymous1337 Naming Conventions:

Example File.

Constants/Macros - All uppercase with _'s in between words: FOO_BAR

Procedures - First word lowercase, next camel-casing. Always use Parenthesis: fooBar()

Methods - First word lowercase, next camel-casing. First word is an action: doSomething()

Keywords - Lowercase: if, then, print, do, locate, while, wend, etc.

Namespaces - All lowercase: foo.bar

UDTs - Uppercase w/ Camel Casing: type FooBar

#includes - Follow the casing of the file: #include "fbgfx.bi"

Variables - First word lowercase, next camel-casing: fooBar

File Names - I develop from my Include folder, so the header files are MyClass.bi, while the code files are anonymous1337.package.subpackage.MyClass.bas. This way you #include as "anonymous1337\package\subpackage\MyClass.bas", install that way, and #inclib that way. It's very consistent.

Procedure Commenting and Variable Declaration:

Code: Select all

type MyType
  '' I use this commenting for variables... and the declaration
  '' is 'as datatype' foo
  as integer foo

  '' task methods
  declare sub doSomething()
    '' do something... this is where I lay my comments for the proc.
end type

Btw the Forums change my casing for keywords... :D

Related Comments - I nest comments which are related (sometimes)... This is the exclusion to 'no collisions' in that if the code below the commenting is nested (such as within a DO/LOOP block), then the indentation of our comments will collide and may confuse the reader.

Code: Select all

'' create a circle
dim as Circle myCircle
    '' set the position
myCircle.setPosition(320, 240)
    '' set the radius
myCircle.setRadius(20)

I have yet to find collisions within my conventions, so just by looking at casing and context, you should be able to tell what it is you're working with. ^.^;;

I know that some people prefer to use do_Something rather than without spacing. Reminds me too much of Constants/Macros, but I can still read it quite easily. Someone's bound to have far better documentation than I do D:

[Eponasoft]

I only apply special rules to variable names, and only in recent works. All variables are prefixed by their type. For example, if I want an unsigned integer, I prefix the variable name with "ui". So, MyVariable becomes uiMyVariable. That lets me know at a glance what type it is. It seems that C coders have been doing this for many years, and it makes a lot of sense.

[KristopherWindsor]

It seems that C coders have been doing this for many years, and it makes a lot of sense.

Actually, I just saw this for the first time last semester in a course on C#. I thought it was ridiculous, and so did the C# chat people. :-P
If you rely on those prefixes you are not naming your variables well. Ie. game_timer would be a Double, since Timer() returns a double, and frame_count would be an Integer since it is always used with += 1.
The same logic you use to determine the variable's type when dimensioning it can be used to determine what type it is in the program, when glancing at code.
We stopped using the QB suffixes (integer%, string$, double#, single!, long&) because it was unnecessary.

IMO. ;-)

BTW, my format is the best. (Look at Orb and Zonaxtic.) :-P

[wallace]

I do everything in lower case unless it's an OpenGL command, then I use the Redbook's syntax, even though I know that it doesn't matter.

I always put a long header at the top of each sub and function saying what it does and what assumptions it makes.

Constants I do all capitalized like in C.

For me every nest gets it's own indention and every matrix manipulation gets indention and every glBeing and glEnd set get indented.

[notthecheatr]

Most things I use first lowercase, then camel-case, as in "fooBar". Constants are usually all-uppercase, however. Internal things (private members of types or variables dim shared but only used in the module) are named all lowercase with underscores, and the first character is an underscore. Most keywords I use the first letter uppercase, the rest small (basically camelcase without the first being small like regular variables) and all procedures I put () after.

http://notthecheatr.phatcode.net/random ... xample.bas is an example of the way I do things; it covers most everything, though there are some other points to note:

(I usually use variable types that are unsigned with the u lowercase, but normally the first character is always capitalized)

I'm very dogmatic about this, I want everything to look spiffy. I have a more complicated thing I wrote about precisely how everything is done, but this gives the general gist of it.

As for namespaces, I generally do all lowercase, but if there are acronyms I will capitalize those (I always capitalize acronyms that are intended to be capitalized, even if it breaks my normal system - likewise, things that are intended to be lowercase, I always keep lowercase no matter what).

Spacing is also very strict, I try not to use too much vertical spaces (blank lines) but where needed I will use them for dividing; I use as many as I think looks good. Basically, I try to make everything logical, consistent, etc.

Filenames (as in #Include) always follow the case of the file, this is to maintain compatibility across all systems. Like regular keywords, the #Include itself capitalizes the first letter. I usually use "Once" as well just in case, even though I also keep "#Pragma Once" in my modules as well.

Other than that, basically I try to name things descriptively and usefully. Comments are also used heavily, but generally I try not to use multi-line comments. Single line comments are always on their own line, the one before the code they refer to, not the same line.

[HD_]

It seems that C coders have been doing this for many years, and it makes a lot of sense.

Actually, I just saw this for the first time last semester in a course on C#. I thought it was ridiculous, and so did the C# chat people. :-P
If you rely on those prefixes you are not naming your variables well. Ie. game_timer would be a Double, since Timer() returns a double, and frame_count would be an Integer since it is always used with += 1.
The same logic you use to determine the variable's type when dimensioning it can be used to determine what type it is in the program, when glancing at code.

The thing is that you are doing the exact same thing, in a more verbose and less flexible way. You are relying on key words such as 'timer' and 'count'- however your method is worse since there is no structure to your naming conventions, 'since we don't need it'. Imagine you wanted to use the words 'timer' and 'count' in some other manner, like something which returns a value true/false after a certain number of frames have passed- now we are returning integers/boolean and it is unclear by your naming convention.

If you are comfortable with it, then something like this would probably be best in my mind:
[var|sub|fnc|obj|typ|tle|etc..][Int|Flt|Dbl|Str|etc..][some name]
eg:
varIntCounter=10l
fncFltSin(45.0f)
It's very obvious what is being referred to, but maybe a little rigorous to type. I haven't used the data type naming convention my self, but I think I will try it in the future.

I am also getting into the habbit of adding the f,d,l after literals (hopefully this doesn't decrease performance, right?).

[C]

I don't use it, but you might be interested in looking up something called 'hungarian notation'

[fbisgood]

I always use the " Modula " style.

Even with the assembly coding, I prefer it and I find the way to apply it somehow; because you see what you are doing and what you will.

I appreciate very much that people; they are very intelligent, logical, and disciplined. Ten bright stars for them... For FreeBasic too of course...

With kind regards.

[marcov]

(this is my policy in general, not FB per se, Pascal oriented, though I also have a Modula past)

Camelcasing everything, parenthesis not mandatory. Constants only uppercase if a (non native) header specifies them that way.

Keywords, namespaces lowercase.

Header files casing, don't care. (but make the files always lowercase for unix/svn purposes, FPC always checks also the lowercase variant to avoid the file casing getting to cumbersome)

In general an absolute ban on hungarian notation, except for variables used visual/designer. This mainly because then you can reuse the identifier for both label and edit, and still quickly navigate through them).

Two spaces identation, also for blocks, block delimiters always on a new line.

[marcov]

I am also getting into the habbit of adding the f,d,l after literals (hopefully this doesn't decrease performance, right?).

No problems now, but maybe in the future I could imagine some problems on embedded targets where "full size" literals are more expensive (32-bit floats instead of 64-bit, 16-bit ints by default etc.

But this is already a bit theoretic.

[elsairon]

My style changes depending on what I'm doing, and what allows me to understand my code better 'at-a-glance', and I have a few loose rules for myself.

- prefer to align code vertically when possible
- no space between a proc and it's parens ( if on the same line )
- always a space between parens, operands, and operators
- always a space between an array var name and its parens
- four spaces indentation in most start...end blocks
- three lines of whitespace between procs
- prefer explicit naming convention
- single line comments describing why, not how
- comments at top of each file saying what it is
- if my code isn't clear (to me), refactor it
- prefer least amount of code to accomplish task

[Eponasoft]

Actually, I just saw this for the first time last semester in a course on C#. I thought it was ridiculous, and so did the C# chat people. :-P
If you rely on those prefixes you are not naming your variables well. Ie. game_timer would be a Double, since Timer() returns a double, and frame_count would be an Integer since it is always used with += 1.
The same logic you use to determine the variable's type when dimensioning it can be used to determine what type it is in the program, when glancing at code.
We stopped using the QB suffixes (integer%, string$, double#, single!, long&) because it was unnecessary.

IMO. ;-)

BTW, my format is the best. (Look at Orb and Zonaxtic.) :-P

That's quite alright, everyone's entitled to their own opinion, even if it's arrogant. No one's format is the best all-around, what matters is what's best for you.

My variables are very well-named. I know what every one of them does because I tend to use long, descriptive names for each, and of course, the prefixes. This is not the same as QB's variable suffixes; those serve an actual, code-specific purpose, whereas using a type prefix is merely for readability. It especially helps if you've come back to an older source code you haven't worked on in awhile.

Good outside examples of this kind of usage can be found in the win32 api headers.

And I think C# is ridiculous. :-P

[marcov]

I only apply special rules to variable names, and only in recent works. All variables are prefixed by their type. For example, if I want an unsigned integer, I prefix the variable name with "ui". So, MyVariable becomes uiMyVariable. That lets me know at a glance what type it is. It seems that C coders have been doing this for many years, and it makes a lot of sense.

That's called Hungarian notation, and hopefully will make most programmers run for the hills. It is always out of sync. It is strangely enough most often associated with Basic, not C. (due to Basic's laxer typing in older versions)

Displaying the proper type for a identifier is the work for an editor/IDE, not for a hand hack.

http://en.wikipedia.org/wiki/Hungarian_notation

[KristopherWindsor]

I am also getting into the habit of adding the f,d,l after literals (hopefully this doesn't decrease performance, right?).

No problems now, but maybe in the future I could imagine some problems on embedded targets where "full size" literals are more expensive (32-bit floats instead of 64-bit, 16-bit ints by default etc.

But this is already a bit theoretic.

Literals are automatically assigned a data type that can properly store the data, so there is not much need to use the f, d, and l options.

The reasons for using them are very minor.
Ie. in this code:

Code: Select all

dim as double x
print x + 1# '# symbol also specifies Double data type

...will save the program the step of converting the constant 1 to a Double before adding to x.
But this is a very minor improvement. ;-)

[marcov]

The reasons for using them are very minor.
Ie. in this code:

Code: Select all

dim as double x
print x + 1# '# symbol also specifies Double data type

...will save the program the step of converting the constant 1 to a Double before adding to x.
But this is a very minor improvement. ;-)

The compiler should be easily be able to fix that. There is no need to insert a conversion into the code if the typing of the operation (+ in this case) is known.

So that leaves us with the same case, but then with an untyped X (e.g. variant)