Code writing standards

[djjd47130]

I hear some people complain that some things which I do in my code are "against delphi standards". Specifically two things...

Assigning variables...

  //This is how I do it:
  MyVar:= MyVal;
  //This is how you're 'supposed' to do it:
  MyVar := MyVal;

Begin on next line...

  //This is how I do it:
  if X > Y then begin
  //This is how you're 'supposed' to do it:
  if X > Y then
  begin

and also...

  //This is how I do it:
  end else begin
  //This is how you're 'supposed' to do it:
  end
  else
  begin

Is there any important things I should know why I shouldn't be doing it this way? Like is there an old version of delphi where it won't compile? Or is this just some stickler making up these standards to keep things neat and clean? Because in my opinion, the way I do it is much cleaner. I try to keep the code compacted as much as possible, while still keeping it clearly readable. Now if for example one line of code gets so long, then of course I may bring begin to the next line, but when it's a short line, why bother?


JD Solutions

 

[Glenn9999]

People tend to have their own opinions about what is "neat and clean" and what is understandable. As far as code goes in this day and age, you want it to be as clean as possible, and easy as possible for the person reading it (someone else other than you or you later on after you forgot what it does) to interpret it so errors aren't made. But since people have their own opinions about what is neat and clean, there are some pretty unreadable source codes out there simply because someone's system tends to be unworkable for the majority of others.

While other languages do have formatting issues where source won't compile, Pascal or Delphi isn't like that. But it's also quite possible to come up with some pretty unreadable, yet compilable code. Personally I've seen some total rat's nests that I just had to reformat or even rewrite because I couldn't decipher it in a reasonable way to make mandated changes to it.

Given that, there are some generally universal "best practices" that are adopted by the majority of people, which are expected in source codes and samples. This is to foster some uniformity, especially in situations where efficiency in others reading your code is a requirement. While there may be differences regarding the practice of these things, there are some situations where you would be forced to adopt someone's coding standards (usually in a "shop" setting) and would be penalized if you didn't do so.

I hope that helped somewhat. I know there are texts on this topic that cover anywhere from a chapter or two to whole books, so it's kind of hard to summarize the whole topic in a few paragraphs. I'm sure there can be much more discussion regarding this topic.

It is not possible for anyone to acknowledge truth when their salary depends on them not doing it.

 

[DjangMan]

I do my begin..end pair formatting like you. I find it helps me to avoid grammar errors that compile but cause grief:

if <something> then
  dothis;
  thenthis;

To keep my code vertically short I'll use one-liners. Again - to prevent me from making the same error above.

if <something> then dothis;

 

[MagicFrisbee]

Delphi has a Code Formatter which I've never used, but I hear it allows you to determine some coding patterns, then it can apply it to source code, without changing the meaning of the code, so that you can read it better. If I inherited a project from a co-worker, for example (we all work on different projects), I'd use the formatter since I don't like what they consider to be neat and clean. Although we can all interpret what any segment of Delphi code is doing, what we can't always determine is WHY. And that's where comments come in handy.

GIS Programmer
City of Orem, UT

http://gis.orem.org

 

[djjd47130]

@DjangMan: Are you forgetting the begin..end; wrapping that block?

if (something) then begin
  dothis;
  thenthis;
end;

@MagicFrisbee: I've used that option in Delphi 2010, but don't think it was in Delphi 7 yet, which is what I'm using currently. D2010 is what my company uses, but I personally use D7.

Speaking of features in later versions, another nifty thing which is in later versions but not 7 is the Refractor, where I can change the name of a variable entirely, without doing find/replace and all that jazz.

JD Solutions

 

[DjangMan]

@JDSolutions: That was an example of what I'm avoiding by always using begin..end when I have more than one statement.

 

[djjd47130]

@DjangMan: Gotcha

JD Solutions

 

[Glenn9999]

Just to kind of stir discussion more than anything since this has potential to be a good one...

Chapters 18 and 19 of Code Complete by Steve McConnell addresses the general issue raised by this thread. (as I side note, I highly suggest this book, it's a good volume of the design and human issues that come into coding, and has definitely improved me as a coder ).

Some random ideas out of it (the actual book explains much more and has coding examples). These are mainly selected as thought provoking ideas that might generate some discussion:

Our studies support the claim that knowledge of programming plans and rules of programming discourse can have a significant impact on program comprehension
...
There is a psychological basis for writing programs in a conventional manner: programmers have strong expectations that other programmers will follow these discourse rules. If the rules are violated, then the utility afforded by the expectations that programmers have built up over time is effectively nullified.

Basically the book goes on to explain that studies have been done to prove that mental organization and recall of information is structured through repetitive exposure of layout and in this respect writing for the human is important when it comes to coding (p 406). In many disciplines, the expert's ability to handle a task is degraded compared to a novice when generally standard organization is removed. Logically when the mental and emotional factors of layout come into play, religious wars can occur (p 406-407). But at a coarse level it is clear that some forms of layout are better than others.

Good layout:
1) Accurately represents the logical structure of the code.
2) Consistently represents the logical structure of the code.
3) Improves readability of the code.
4) Withstands modification of the code.

Use of white space enhances readability. Spaces, tabs, line breaks, and blank lines are tools available for you to show a program's structure. The analogy of a book is useful for explaining what is useful practice. For example, related statements can be grouped together into paragraphs with white space occurring between them to denote unrelated statements.
...
Visual alignment can enforce the idea that a group of statements belong together.
...
Use indentation to show the logical structure of a program. Indent statements under the statement to which they are logically subordinate.

Use more parentheses than you think you need. Use parentheses to clarify expressions that involve more than two terms. They may not be needed, but they add clarity and don't cost you anything.

Due to the general need and expectation of consistency in layout, especially for situations with multiple programmers, many use source code formatters or beautifiers to standardize the appearance of their code.

It is not possible for anyone to acknowledge truth when their salary depends on them not doing it.

 

[Glenn9999]

Regarding individual statements (same book as referenced in previous posts):

Limit line statement length to 80 characters
...
Use spaces to make logical expressions readable.
...
Use spaces to make array references readable.
...
Use spaces to make routine arguments readable.

Formatting lines that need continuation:
Make the incompleteness of a statement obvious.
...
Keep closely related elements together.
...
Use a standard rule for indentation of continuation lines, either the amount used for logical structures or under the first argument.
...
Make it easy to find the end of a continuation line.
...
Indent assignment continuation lines after the assignment operator.
...
Use only one statement per line.

The book says much more, but I thought it might be interesting to throw out a few things for discussion, especially since much in this matter is a YMMV affair.

It is not possible for anyone to acknowledge truth when their salary depends on them not doing it.

 

[djjd47130]

Very interesting... More specifically that someone would take the time to write a whole book about this issue. I can understand the mental and psychological aspect of it. My colleague's coding style is extremely unique, he indents by 3 instead of 2, sometimes indents some odd number like 12 when the previous line was just 4. He also breaks things down into multiple lines very often.

After working with his code, I've realized he doesn't want anyone else to touch his work. He built it in a way where if we wanted something done, we would have to ask him to do it, thus giving him more work to do (and in the end gets paid for it).

JD Solutions