I was playing with CGE again and I want to propose new project templates. My proposal is to refit the indentation, rephrase comments, apply Borland/Embarcadero Codibg Style guide to identifiers and use more verbose code (i.e. redundancies as Self and such).
My question is, should we discuss it here or should I just push a pull request? And in case of pull request, a pull per template or a single one with all them?
We can discuss here, or if you want — you can submit a pull request (I suggest to one template first), and let’s discuss in PR. Some of the things you mention – are either already done in my eyes, or I don’t think we should do it :), so they warrant a discussion. At the same time, the discussion will be probably more concrete if I see the exact changes you propose.
IOW, I agree with the spirit of the changes you mention – we want the templates to present a code that is clean, looks standard to a Pascal developer, and we want them nicely documented. I’m not sure do I agree with some exact details you mention 
Let’s talk!
Note that we have our own coding conventions Coding Conventions | Manual | Castle Game Engine , though most of Pascal conventions there are deliberately just the same as what I saw in both Lazarus and Delphi codebases.
To address some things you mention:
Indentation and following Embarcadero coding style – sure, we want to follow them in general, our Coding Conventions | Manual | Castle Game Engine are generally consistent with Embarcadero style from what I know. Where do we differ from coding style and indentation?
Rephrase comments: sure, I’m open to improving them. What do you miss?
“Redundancies as Self” – If I understand correctly what you mean (calling methods with Self.Xxx instead of Xxx) – this is something I explicitly do not want. It would be a lot of Self. additions that are ultimately unnecessary. Pascal says you can omit Self in Self.Xxx, just like most other languages, and we use this feature. From what I see, so does most existing Lazarus and Delphi codebase.
Though it is possible I misunderstand this point, i.e. maybe I don’t understand what you meant by “redundancies as Self and such”. Discussing this in PR is absolutely welcome
I’ve read your Coding Conventions and I’ve found they’re quite different than mine. Actually I do the opposite in some cases 
(for example, units order in uses clause). I think my proposal won’t be accepted; no problem with this though.
Since it’s easy to change CGE templates I think I’ll finish my templates, then upload to GitHub as a new project so people can use them, and discuss them and maybe adapt some parts to the current templates.
Understood, all good.
I’m still open to talking about it. Because I think CGE coding conventions generally follow Lazarus / Delphi codebases I saw, I really didn’t want to propose something controversial there
E.g. units order to which you refer, Coding Conventions | Manual | Castle Game Engine : the idea is that in most applications, it should not matter at all, but in edge-cases, we want application-scoped identifiers to obscure engine identifiers, and engine identifiers to obscure standard units. But, in the ideal world, there should be no conflicts thus no obscuring. I think this follow general notion. E.g. I’m looking now at Lazarus unit CocoaWSComCtrls having uses clause:
uses
// RTL, FCL, LCL
MacOSAll, CocoaAll,
Classes, LCLType, SysUtils, LCLMessageGlue, LMessages,
Controls, ComCtrls, Types, StdCtrls, LCLProc, Graphics, ImgList,
Math,
// WS
WSComCtrls,
// Cocoa WS
CocoaPrivate, CocoaScrollers, CocoaTabControls, CocoaUtils,
CocoaWSCommon, CocoaTables, cocoa_extra, CocoaWSStdCtrls, CocoaGDIObjects, CocoaButtons;
So LCL does follow similar conventions. Units order is roughly from “most general” to “most local / specific”.
Anyhow, this is all subject to discussion and possible improvements
I didn’t thought about overriding stuff, because I like to use unit names to refer the one I want to use (that’s another example of “being verbose” and that).
By the way, maybe the most annoying thing I see is the indentation. Let me paste a little example of how I indent code:
unit ExampleUnit;
(* An example of how I do indentation in my code. You'll see some original
things here, like how I align the comment blocks and other stuff.
Pay attention to the next line!
*)
interface
uses
sysutils, Classes,
UnitUsed, AnotherOne, Blablablah;
const
(* This explains the next constant. *)
ValueUsedSomewhere = 10;
(* Now, a procedure declaration. *)
procedure RoutineThatDoesSomething (aParameter: Integer);
implementation
uses
StringUtils; { For example. }
procedure RoutineThatDoesSomething (aParameter: Integer);
begin
{ And here, we have some code (random, at the moment). }
if aParameter < 10 then
WriteLne ('The value is small.');
{ I think you get the idea.
By the way, I want to show some extreme cases because maybe you find
them interesting.
}
CallingWithLotOfParameters
(
'A value here',
ValueThere,
123123123,
YabadbaDoo
);
if (VeryLargeName <> AnEvenLargerNameThanTheOther)
and (VeryLargeName <> AnotherThing)
then
begin
Blabla := aParameter;
CallSomething (aParameter + 1)
end
end;
end.
I don’t know how do you see it. I understand that it adds more indentation but I find it more easy to read than most of other’s code I’ve seen out there; specially the long routine call and the long if statement are quite easy to find the ending. Note that I use Vim mostly and it is a bit uncomfortable with long lines; I tend to use up to 80 character lines but I exceed that limit sometimes when I feel it.
The conversation is interesting and I would like to give my opinion.
Regardless of some important basic conventions, I do not share the idea that a code must necessarily adhere to a pre-established structure.
Every code bears the signature of the person who wrote it, and this manifests itself primarily in the indentation.
Assuming that a given begin cannot have its end unaligned, or the assignment of multiple variables cannot proceed in a zig zag, etc., because it would make the code unreadable, specific statements or indentation should not be imposed.
For example:
uses
// RTL, FCL, LCL
MacOSAll, CocoaAll,
Classes, LCLType, SysUtils, LCLMessageGlue, LMessages,
Controls, ComCtrls, Types, StdCtrls, LCLProc, Graphics, ImgList,
Math,
// WS
WSComCtrls,
// Cocoa WS
CocoaPrivate, CocoaScrollers, CocoaTabControls, CocoaUtils,
CocoaWSCommon, CocoaTables, cocoa_extra, CocoaWSStdCtrls, CocoaGDIObjects, CocoaButtons;
tidy and precise, personally in C# I do it with the variables declared in MonoBehaviour. I list groups of variables that refer to specific objects so that the user can identify them more easily.
But what about:
CallingWithLotOfParameters
(
'A value here',
ValueThere,
123123123,
YabadbaDoo
);
I prefer to write:
CallingWithLotOfParameters (
'A value here',
ValueThere,
123123123,
YabadbaDoo );
As well as:
if (VeryLargeName <> AnEvenLargerNameThanTheOther)
and (VeryLargeName <> AnotherThing)
I prefer:
if (VeryLargeName <> AnEvenLargerNameThanTheOther) and
(VeryLargeName <> AnotherThing)
Again, as an example, in C#:
if (a == 1) {
[...];
}
rather than
if (a == 1)
[...];
while in Pascal I would never write
if (a = 1) then
begin
[...];
end
In short, it’s my opinion, but I wouldn’t like to adhere to a pre-established code formatting standard.
All codes are fine if they follow the basic general conventions and then differ in small details, in their structure, which ultimately are nothing more than the expression of whoever wrote them.
I can say my opinion. It may be some benefit, because CGE is a my single Pascal framework (besides Lazarus). And I remember (or have 
) the newbie-view.
Generally, I like the current CGE codestyle. It seems understandable enough. Few aspects I used intuitive without the reading of the Conversations.
What I might have written differently had it not been for the Conversations:
Also sometimes I feel that Pascal code is huge, but this is the feature of the language. And I think it is solvable by the good functions and the code organization.
Well, the way we all write code (and comments) is a matter of preference, definitely
That is, we become accustomed to our own style. And 20 years later, we find our style most readable, while other style … less readable If we read a code written by someone else, with different preferences, it may look unreadable – we know it goes both ways. We are all accustomed to our coding style, or coding style of the project we use most.
( That’s not to say that there aren’t “worse” or “better” coding styles. An inconsistent style is definitely worse. A style where one cannot clearly see where blocks (begin…end) start and finish is definitely worse, I think. In general, a style that is unreadable is worse… but then “what is readable” is also a matter of taste in many (though not 100%) cases. )
Admittedly, for me the comments style proposed by @NiunioMartinez in Project templates - #5 by NiunioMartinez look less clear than the style we have in Castle Game Engine and I’m accustomed to. But I absolutely know that it “goes both ways” (i.e. if you’re accustomed to your style, then likely CGE code looks weird). In this case, I can see both styles as completely reasonable.
In general, I think that having a coding style set in a project is a good thing. All the contributions should follow the similar style, so that everyone developing adjusts to the same style and eventually finds it workable, after some time. I’ve been in (not CGE related, not even Pascal related) projects where different devs used various style – this resulted in problems when trying to modify. When each file, or even each routine, or even each line, followed a bit different conventions, depending on “who touched it last”. This makes the job of the contributing person harder – what conventions to follow? Should you change everything you touch to what suits you? But this makes additional work (both for writing code, and it makes reviewing harder due to style changes mixed with actual logic changes).
It is also best to choose conventions that follow other projects. I think Castle Game Engine is a bit closer to the “most common” conventions in this regard. Looking at both Delphi and Lazarus source code, I think CGE is more similar. Again, I emphasize, this is a matter of preference – you can definitely invent many reasonable (consistent, readable once you’re accustomed to it…) ways to indent. So it’s not that CGE style is “more readable on its own” than style of Project templates - #5 by NiunioMartinez , but I think it is more readable because it matches more what others (like Delphi or Lazarus) are doing.
To point out to some particular differences, in CGE:
Most comments are before the documented item. Not after.
Note that this is also required by PasDoc ( Where To Place Comments | PasDoc ) to properly assign comments to items (one can use “back comments” in PasDoc to assign comment to preceding identifier, but still by default comment is assigned to following identifier). Note: I’m the PasDoc current maintainer and CGE is using PasDoc. So it’s not an accident that CGE style also conforms easily to PasDoc rules But I didn’t invent this PasDoc rule, it was there from the beginning, way before I joined PasDoc development.
Most comments are { } or // . We use the (* *) comment only when there’s a reason for it, e.g. we need to have { or } inside.
The comments are at the same indentation as the things they apply to. E.g. if you comment an indented variable, comment it also indented. If you comment inside an implementation, you indent just like the line you are commenting about.
We break line after operators like and, not before them.
We don’t line break before then.
We put ( on the same line as routine call.
Similar to what @valterb shows, while I absolutely would also split the call into many lines (though maybe not one line per argument, at least not usually), I would keep CallingWithLotOfParameters and ( together. Without line break, without even space. Again, nothing “objectively better” in my approach I think (and I’ve seen many devs putting space between routine name and space in various programming languages, makes sense). It is just more “something I’m accustomed to”. And in this case I think others do it usually like me, again looking at random Lazarus and Delphi code.
Though note that we follow actually a “1 line per argument” style for Format and similar calls. Not from the beginning of CGE, but from few years I try to write things like this:
Format('something something %d: %s', [
MyNumber,
MyString
]);
I tried to objectively look at Lazarus sources, at code which I never touched (to be fair), I think Lazarus is mostly like CGE. See e.g. lcl/calendar.pp · main · FPC / Lazarus / Lazarus · GitLab .
( Note that I didn’t look at FPC code. FPC (at least compiler, but also some RTL parts) follows it’s own style, a bit unique – Coding style - Free Pascal wiki . But, again, I guess FPC devs would say the same thing as I repeated above – “it’s a matter of preference, FPC style is something we’re accustomed to by now”. )
I understand and coincide in some points.
My style is quite eclectic but following most Borland/Embarcadero directives (IIRC, because I changed a few things since last time I read it).
I’ll try to adapt myself to CGE style in my next proposals then.