A book about Object Pascal Style Guide

[Guest]

I know this is a controversial topic, but nonetheless it deserves some attention.

 

I wrote a book about style guides for Object Pascal, after so many years in different projects with different approaches into coding style. Being a Certified Delphi Developer I would of course prefer a formalized style guide, but with colleagues rarely aware of style guides available, it has been difficult to work in environments with changing degree of arbitrariness.

 

Beside raising awareness of available style guides, the book has been an exercise in writing a book. Obviously, it takes some time to write a book, and the experience will determine a pursue into 3-4 other titles about programming.

 

This book is free and although written in English, it is not my mother tongue, and thus lacking proofreading. Being a free book proofreading by professionals in English was not and option.

 

I hope this can be of some help in a more pragmatic view of coding styles, or a more professional approach to style guides. At least it cost nothing. The book in PDF format is available at:

 

https://sourceforge.net/projects/object-pascal-style-guide/

 

Best regards,
Normann
 

[David Heffernan 2345]

This looks very interesting.

 

After a quick skim of one topic on I note that there's an error on page 89 that is worth addressing. LTextFile is protected by a try/finally but created after the try rather than before the try. 

 

In that example I'd also put the try of the try/except immediately after the assignment to Result rather than two lines before it. 

 

For what it is worth I'm sure that if you had posted here then quote a few people would have read your book and looked for errors and given feedback. I would happily have done so and would still do so. 

Edited February 19, 2022 by David Heffernan

[Guest]

Hi David.

 

I appreciate your feedback, and I will take a look at the example and find a simpler construct.

 

I don't mind correcting errors and release a second edition with fixes. The idea of making it available on sourceforge was to release editions of the book, and release the Word documents as well, so people can make updates and perhaps even translations of the book.

 

It should evolve into something of its own 😉

 

Best regards,

Normann

 

[David Heffernan 2345]

1 hour ago, Bent Normann Olsen said:

I will take a look at the example and find a simpler construct.

I don't think the issue is complexity, the example is fine. it's just a couple of minor inaccuracies. That said, I'd strip out the FileExists check and just focus on the exception handling:

  LTextFile := TStringStream.Create;
  try
    LTextFile.LoadFromFile(AFileName);
    Result := TMemoryStream.Create;
    try
      Result.LoadFromStream(LTextFile);
    except
      FreeAndNil(Result);
      raise;
    end;
  finally
    LTextFile.Free;
  end;

If you'd like people to comment on the entire book, do ask!

Edited February 19, 2022 by David Heffernan

[Stano 143]

I read a quality book on the subject. (Perfect Code - Steve MCConnell - 2005). I still want to read yours. I don't know English, so I use google transaltor. If you have the text itself, it would help me. Now I need to copy the text from the PDF first. Remove unnecessary spaces. The add-on to remove them doesn't work for me. Only then translate.
Then I'll send you a translated book. Although I don't know if he will be interested in Slovak translation (Czechs also understand him).
If I find a shortage with blind eyes, I'll let you know.

Edited February 19, 2022 by Stano

[Guest]

1 hour ago, Stano said:

I read a quality book on the subject. (Perfect Code - Steve MCConnell - 2005). I still want to read yours. I don't know English, so I use google transaltor. If you have the text itself, it would help me. Now I need to copy the text from the PDF first. Remove unnecessary spaces. The add-on to remove them doesn't work for me. Only then translate.
Then I'll send you a translated book. Although I don't know if he will be interested in Slovak translation (Czechs also understand him).
If I find a shortage with blind eyes, I'll let you know.

Sorry about that. I have upoaded the document in Word-format (*.docx) and i OpenDocument-format (*.odt) as well. You should be able to find the documents under Files at sourceforge.net.

 

Hope these will help you.

[Guest]

2 hours ago, David Heffernan said:

I don't think the issue is complexity, the example is fine. it's just a couple of minor inaccuracies. That said, I'd strip out the FileExists check and just focus on the exception handling:

  LTextFile := TStringStream.Create;
  try
    LTextFile.LoadFromFile(AFileName);
    Result := TMemoryStream.Create;
    try
      Result.LoadFromStream(LTextFile);
    except
      FreeAndNil(Result);
      raise;
    end;
  finally
    LTextFile.Free;
  end;

If you'd like people to comment on the entire book, do ask!

 

I took a look at the code, and there is nothing wrong with the example. Changing it would remove the point of not raising exceptions if it can be avoided with simple if-statements, and it will remove a little hint on how to protect multiple resources.

 

I would agree the example could be better, and I will work on a construct that should highlight the intent of the construct, and a better explanation of the construct.

 

Asking people to comment the entire book was not my intention. Sorry about that, but I don't mind any feedback. I do actually appreciate any feedback.

 

Thanks.

[Stano 143]

Really. I didn't notice it. Well thank you.

[David Heffernan 2345]

1 hour ago, Bent Normann Olsen said:

I took a look at the code, and there is nothing wrong with the example.

Yes there is. I explained what was wrong in my first comment. The try of the try/finally is before the local variable LTextFile is assigned, but it should be immediately after it. 

[David Heffernan 2345]

1 hour ago, Bent Normann Olsen said:

Changing it would remove the point of not raising exceptions if it can be avoided with simple if-statements

Not really. The call to LoadFromStream could fail.

[Guest]

17 minutes ago, David Heffernan said:

Not really. The call to LoadFromStream could fail.

And still the construct will work.

 

I will rewrite the construct so its focus remains on simple if-statements, rather than slight odd try/finally and try/except constructs.

[David Heffernan 2345]

3 minutes ago, Bent Normann Olsen said:

And still the construct will work.

 

I will rewrite the construct so its focus remains on simple if-statements, rather than slight odd try/finally and try/except constructs.

Perhaps I misunderstood the point you were trying to make, but that pattern of returning a newly created instance, with a Free in the except block is useful. Even then the FreeAndNil isn't needed because Result is not seen by the caller.

[Anders Melander 1782]

4 hours ago, David Heffernan said:

 

...
  except
    FreeAndNil(Result);
    raise;
  end;
...

 

What? No comment on the pointless use of FreeAndNil? Ah. There it was 🙂

 

which ironically is preceded by this statement:

Quote

And because developers can have difficulty in understanding what is happening, they have tremendous disputes when it comes to protecting multiple resources in case of exceptions. In most cases developers simply add nested try/finally block for each resource they want to protect, just to be sure, and it shows in stylization, e.g.:

Source := TList.Create;
try
  Target := TList.Create;
  try 
    // Manipulate Source and Target 
  finally 
    Target.Free; 
  end; 
finally
  Source.Free;
end;

Above example show the level of insecurity of a developer [...]

Color me insecure then.

Edited February 19, 2022 by Anders Melander

[Guest]

I am sorry. I should have worked on better examples, especially on exception blocks.

 

I have taken steps in removing the current edition. Sorry for any inconveniences. Perhaps it's just not ment to be.

 

Best regards.

[Guest]

There's one thing... one. I hate when the prefix chars for local vars or arguments start with an uppercase char.

 

function Name(const AArgument: TType); // Ouch!

function Name(const aArgument: TType); // Yeah!!!

 

Both of the above look good.

 

funciton Name(...);

var

  lVariable...

 

function Name(...)

var

  LVariable...

 

The second one looks bad IMHO. For readability lowercase prefix chars. But T has always been uppercase. So this is tricky.

 

This inconsistency (also present i VCL sources) is annoying, IMHO. 

 

Another thing is that a lot of Delphi peeps has started to prefix records with R rather than T. T is for "type" which includes records. But records ARE very usable and the difference between object pointers and records on the stack beggars for a difference. Tricky, that too, IMHO.

 

I hope this was a bit creative.

 

 

[David Heffernan 2345]

4 minutes ago, Bent Normann Olsen said:

I am sorry. I should have worked on better examples, especially on exception blocks.

 

I have taken steps in removing the current edition. Sorry for any inconveniences. Perhaps it's just not ment to be.

 

Best regards.

Why don't you let us give you extra sets of eyes? 

[Guest]

I really must agree with Heffernan here. These woods are laden with worms and wine.

It is not something to just present.

@Bent Normann Olsen, i have only browsed/skimmed the reasoning, but it looks like it would beggar it's own book (wery well written).

Do not devalue your effort because of one or two problems, it is a very good start!

Everything needs to start somewhere.

Edited February 19, 2022 by Guest

[Bill Meyer 337]

2 hours ago, Dany Marmur said:

These woods are laden with worms and wine.

And conflicting opinions are everywhere. 😉

[Anders Melander 1782]

2 hours ago, Bent Normann Olsen said:

I have taken steps in removing the current edition. Sorry for any inconveniences. Perhaps it's just not ment to be.

That would be a pity. I found it well written with excellent and relevant content.

 

Unfortunately my own experience is that those that need a style guide the most are also those that are the least likely to read something like it. In my current position one of my responsibilities is to be the source code gatekeeper; I review each and every check-in for code style, bad patterns and obvious weaknesses. We need this because many of our developers are fresh out of school and inexperienced or mainly has C# experience. On top of that much of our code were written by amateurs loooong time ago and is simply horrible. On our required reading list is a very thorough style guide which I repeatedly have to refer to when people, including our lead developer, produce code that plainly demonstrates that they haven't read it. Apparently they simply haven't understood the benefits of adherence to a common code style in a large code base.

[Anders Melander 1782]

2 hours ago, Dany Marmur said:

These woods are laden with worms and wine.

Quote

But we have promises to keep.
And miles to go before we sleep.

And miles to go before we sleep.

 

I knew it!

 

https://www.imdb.com/video/vi2049426201

 

[corneliusdavid 214]

21 hours ago, Bent Normann Olsen said:

https://sourceforge.net/projects/object-pascal-style-guide/

I clicked on the link and it can't be found; searched for the title and couldn't be found either.

[angusj 126]

On 2/20/2022 at 3:54 AM, Bent Normann Olsen said:

I have taken steps in removing the current edition. Sorry for any inconveniences. Perhaps it's just not ment to be.

16 hours ago, corneliusdavid said:

I clicked on the link and it can't be found; searched for the title and couldn't be found either.

See above. While I also missed downloading and reading Normann's book, it seems he wasn't encouraged by the initial feedback. I think there's a lessen in that. Normann had put considerable effort into writing this book and uploaded it as a free resource and, from what I can glean from this thread, it was mostly of high quality.

Edited February 20, 2022 by angusj

[dummzeuch 1505]

When posting something's like this, one has to expect feedback. And usually negative feedback more than positive. It's difficult to deal with that if you have no experience.

 

Most people have no idea how much work is takes to write a book.

(I don't either, I only write blog posts and wiki articles.)

[Stano 143]

If you want, I can put a PDF attachment and * .docx. Perhaps the author is not angry.

[dummzeuch 1505]

13 minutes ago, Stano said:

If you want, I can put a PDF attachment and * .docx. Perhaps the author is not angry.

Don't. Either he will put it back online himself, or he won't. It's his work after all.