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.

[Ñuño Martínez]

(...)

I like your style.

[Darkhog]

Note that this is written before reading actual article. Here are my thoughts on the subject.

I always try to keep my code readable, simply because I often "jump between projects" - I have three Pascal projects right now (game engine, Super Heli Land and DCPU-16-like virtual processor) and two RPG Maker ones (plus one on hiatus until I'll get more skilled with RM because of magnitude of it) and when I get bored with one project I am going to other. So often I have few month breaks from one project.

Because of it, I've learned to write easy to read code. For my identifiers (variables, procedures and functions) I'm using CamelCase (with first letter upper case), for constants it is all uppercase. Sometimes for procedures/functions I'm using underscore_notation, but only when code readability suffers from usage of CamelCase or when I'm writing some library and want to visually separate its name (example: DarkhogGui_DrawButton).

I also do lots of commenting. Even most insignificant and obvious line should be IMO commented, because after few months you won't know what it does.

[SilverWarior]

I also do lots of commenting. Even most insignificant and obvious line should be IMO commented, because after few months you won't know what it does.

Commenting is verry important but I keep forgetting to coment my code myself

[pitfiend]

Commenting is verry important but I keep forgetting to coment my code myself

Don't feel like an alien, it happens to many programmers, myself included. But well writen code is a good documentation in itself if you name your functions/procedures and types/const/variables/classes/properties with meaning names.

[Darkhog]

Don't feel like an alien, it happens to many programmers, myself included.

It happens to me too. I usually put comments after I'm certain code is doing what is supposed to do.

But well writen code is a good documentation in itself if you name your functions/procedures and types/const/variables/classes/properties with meaning names.

Yeah, about that... I'm not big fan of "self documenting code". I had many times read code that was supposed to be "self documenting one" but wasn't easy to grasp (though easier than if variables were called "Variable1","Variable2", etc. and functions "Function1","Function2",...). And it was both Pascal and other language code (which includes so easy, at least for me, languages like C# or Java).

In my opinion nothing will help more than properly documented code. Even comments like "this function is supposed to do..." before function body are good.

[Carver413]

I hate comments in the code,it just makes it harder to visualize the actual code. I really hate people who indent 8 char at a time, 2 is enough.

[SilverWarior]

I hate comments in the code,it just makes it harder to visualize the actual code. I really hate people who indent 8 char at a time, 2 is enough.

I don't hate coments in the code unles they span through several lines. Those can realy make hadred to visualize the code.
The best thing to help bisualize the code are region definitions and code folding that is of course if they are used properly. It is to bad they are somwheat broken in Delphi. If you make any syntactical error all the code that is below that point gets unfolded automaticaly. This unfortunately makes code foldin almost uselsess in Delphi.
I myself use 4 char indents mosty 2 in type declarations only. The main reason for this is old practice from Delphi 6. Since Delphi 6 didn't support automaticly adding "end;" after every "begin" I dah to rite all those ends by myself. And since end is 4 characters long I kept 4 char indets as it alowed me to simply pres UP arrow key to get in place for writing the code inside the method I just started to write.