Article: Why Code Readability Matters

[phibermon]

I tend to vary my notation depending on context for example, for a large number of type declerations that get used often, I'll shorten the terms but also include information pertaining to that type ie :

SInt8 - Signed 8bit Integer
UInt8 - Unsigned 8bit Integer etc
SInt16
UInt16
SInt32
UInt32
Float32
Float64

So this is similar to a lot of C stuff, OpenGL etc. I don't use classic hungarian notation simply because it's an old technique that isn't needed with modern code editors.

For class definitions and methods I tend to use the most descriptive terms (in CamelCase) and group together classes by name whenever it seems appropriate :

TJSpatialRegion
TJSpatialEntity
TJSpatialEntityController
TJSpatialEntityControllerAnnotation

I always use the prefix 'A' on variables in method declerations so there can be no confusion between private variables (F). class Properties exposed to end-users use no prefix.

FVelocityVector : TJVec3;
FSpatialController : TJSpatialController;

procedure TJSpatialEntity.SetVelocityVector(AVelocityVector : TJVec3);
procedure TJSpatialEntity.SetSpatialController(AspatialContr oller : TJSpatialController);
procedure TJSpatialRegion.AddSpatialEntity(ASpatialEntity : TJSpatialEntity);

property VelocityVector : TVec3 read GetVelocityVector write SetVelocityVector;

I think that naming conventions are important for either :

A) Adoption Speed - If you intend your code to be accessed by a large number of people, you'll want it to be as descriptive as possible.

B) Coding Speed - If it's just you or a small team and the source is closed then use whatever shorthand is appropriate in order to save on time writing/reading the code.

Very large code-bases require all coders to use the same system for notation if only to avoid adding additional complexity into already complex systems.


P.S I would not recommend using layout rules with the intention of making the language syntax easier to read! that's why we have syntax highlighters etc. If you're doing a whole bunch of keystrokes to bring code-completion in line with your own layout, you're just wasting time. Use the layout defined in your editors snippets. Questions of notation should be about understanding what your code does not how the language works.