Article: Why Code Readability Matters

[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.

[Carver413]

I hate code folders as well. to me they are simply a bandaid to an editor design that should have went away long ago. with the Explorer I have an editor design that allows me to qucikly move to where I want to work and see only what I am working on.

[SilverWarior]

I don't think I quite folow what you wanna say.

[Rodrigo Robles]

These days follow code conventions is just a obligation. People just not accept non-standard code anymore.
I believe the next step to code quality is to focus in a reusable design and eliminate redundancies. Today I see in many production projects redundant code in many levels - some people make ctrl+c and ctrl+v in many lines of code or even a entire unit to make a new form looks like the other.
Another problem is bad design - giant functions that do many things and are completely specialized and not-reusable.
Unnecessary coupling is very common in Delphi - specializing units that could be more generic and reusable.

[Ñuño Martínez]

I don't know what "region definitions" are. Do you mean to use your home language (Spanish, French, German...) or what?

[SilverWarior]

I don't know what "region definitions" are. Do you mean to use your home language (Spanish, French, German...) or what?

No Ñuño we are talking about this:
http://docwiki.embarcadero.com/RADSt...kyo/en/Regions
http://wiki.freepascal.org/IDE_Windo...7B.25Region.7D

[Ñuño Martínez]

Oooh! I see. Thanks for the tips, SilverWarrior.

I think I never used code folding. I know it exists but I never feel like I needed it. I'm not saying it isn't useful.

[SilverWarior]

I think I never used code folding. I know it exists but I never feel like I needed it. I'm not saying it isn't useful.

Well if you use code folding features that Delphi offers you by default it basically boils down to just folding of type definitions, method implementations, and entire unit sections (uses section, interface section, implementation section, var and constant sections, etc.) you probably won't see many benefits. In fact in certain cases it might even hurt. For instance if you fold a method in implementation section it beings to look just like forward method declaration and could thus cause confusion since the only clue that code was folded is that minus sign at the beginning of the line. Some other coding tools at leas also add a vertical line to the line where code was folded to give more clear information that the code was folded.
But if you start using regions and thus add yourself more code folding points you will learn that it could actually be useful in certain scenarios. Especially if you have a tendency of writing long method or what I call "a mile long nested if clauses". In such cases code folding can come very useful.
In fact when I used code folding for the first time (with the help of regions) was to get heads and tails of some badly written code that I found on internet.