Source code formatting guidelines

Hi guys,

is there any document I can read on how Pharo source code
is/should be formatted? I mean things like
- tabs/spaces? How many spaces if spaces?
- encoding of the source string
- trailing newlines
- trailing spaces
- ...

I don't care much about things like whether there should
be a space after ^, opening [ and so on (because there's
a little I can do about it :-)

Best, Jan

Hi

I find the formatting chapter of the 'Smalltalk best practices pattern, Kent Beck' really nice but I cannot find a free pdf.
I just found http://sdmeta.gforge.inria.fr/FreeBooks/WithStyle/SmalltalkWithStyle.pdf. There is also a chapter about formatting. Should also be a good reading.

Regards,
Christophe.

Le 19 nov. 2014 à 12:06, Jan Vrany a écrit :

Hi guys,

thanks for replies. I read books mentioned by Christophe years ago,
they're worth reading indeed.

But as I said, I'm more interested in 'low level' details like I
mentioned:
- tabs/spaces? How many spaces if spaces?
- encoding of the source string
- trailing newlines
- trailing spaces
- ...

The reason is I'm now working with Jan K. on some stuff and he's
using Pharo while I don't. To exchange code I read his .mcz when
merging his changes and generating .mcz for him when he has to merge
my stuff. However, Pharo's merge tool apparently does not do a
really great job when it comes to whitespace changes so the merge
is difficult and error-prone.
The idea is to transform the source just before spitting out the .mcz to
minimize these false-diffs when one try to merge.

Best, Jan



On Wed, 2014-11-19 at 15:19 +0100, Nicolai Hess wrote:

Hi guys,

thanks for replies. I read books mentioned by Christophe years ago,
they're worth reading indeed.

But as I said, I'm more interested in 'low level' details like I
mentioned:
- tabs/spaces? How many spaces if spaces?
- encoding of the source string
- trailing newlines
- trailing spaces
- ...

The reason is I'm now working with Jan K. on some stuff and he's
using Pharo while I don't. To exchange code I read his .mcz when
merging his changes and generating .mcz for him when he has to merge
my stuff. However, Pharo's merge tool apparently does not do a
really great job when it comes to whitespace changes so the merge
is difficult and error-prone.
The idea is to transform the source just before spitting out the .mcz to
minimize these false-diffs when one try to merge.

Best, Jan



On Wed, 2014-11-19 at 15:19 +0100, Nicolai Hess wrote:

IIRC, the .bin is the entire source string in Datastream-format, that is, is a datatype identifier (either ByteString or WideString), followed by the raw bytes/words (which is pure Latin1 if ByteString, UTF32-BE(?) for WideString, at least since leadingChar of the standard Unicode locale was changed to 0). So writing an encoder/decoder strictly for use with MCZ's isn't a very big task. (this is what gemstone does)

The pure text file (.sources) is only used as a fallback** when importing code where the .bin is corrupted/absent, it should either be pure latin-1, or UTF-8*.

Cheers,
Henry

* Not sure if it ended up being solved using a BOM-marker for UTF8 (as in the .cs format), or if a UTF8Encoder is used by default, with a fallback to latin1 if an incorrect utf8 character is encountered.
** Ironically, the string export was bugged up until recently, causing lots of confusion when non-latin1 .mcz exported/imported just fine in Squeak/Pharo, but failed to import elsewhere (where the .bin reading was not implemented)

Hi,

On Thu, 2014-11-20 at 16:47 +0100, Henrik Johansen wrote:
That's what I do as well, but was not 100% sure about the encoding.
Thanks!

>
> The pure text file (.sources) is only used as a fallback** when
> importing code where the .bin is corrupted/absent, it should either be
> pure latin-1, or UTF-8*.
>

OK, thanks. I do not use .sources file, only .bin :-) But good to know
it should be UTF8

Thanks!

> Cheers,
> Henry
>
> * Not sure if it ended up being solved using a BOM-marker for UTF8 (as in the .cs format), or if a UTF8Encoder is used by default, with a fallback to latin1 if an incorrect utf8 character is encountered.
> ** Ironically, the string export was bugged up until recently, causing lots of confusion when non-latin1 .mcz exported/imported just fine in Squeak/Pharo, but failed to import elsewhere (where the .bin reading was not implemented)
>

2014-11-19 14:55 GMT+01:00 Marcus Denker <[hidden email]>:

On 19 Nov 2014, at 14:47, Peter Uhnák <[hidden email]> wrote:

how Pharo source code is formatted

One could argue that this is equivalent to the default settings of Pharo formatter.

Which is not good… e.g. it always adds too many line breaks…

Marcus

If we can agree on source code guidelines, we should change the default settings of the Pharo formatter accordingly.

Yes I would love that. I nearly like the default formatter except that sometimes it creates too
many line breaks.

What we could do is to build a sample and go over it.
Ideally I would like to have formatting as you type :).

And concretely I would like to format all the code. I'm doing that when I change something.

On 29/12/14 08:54, stepharo wrote: I'm still missing the RB based formatter in Dolphin. It's comparable to
the Pharo one (layout wise) but created less "line-break-noise" :-)

It should be easy create an RBFormatter with the same settings in
Dolphin to. But the current format didn't yet annoy me enough to
transfer it.

> What we could do is to build a sample and go over it.
> Ideally I would like to have formatting as you type :).
Even something simple like automatic "format-on-save" (optionally) would
help IMHO.

Especially as the format hotkey doesn't work reliably on Mac OS X -
still have to chase why.

> And concretely I would like to format all the code. I'm doing that when
> I change something.

CU,

Udo

I'm still missing the RB based formatter in Dolphin. It's comparable to
the Pharo one (layout wise) but created less "line-break-noise" :-)

;-)
I think that it should not be that difficult to arrive to a good compromise

> It should be easy create an RBFormatter with the same settings in
> Dolphin to. But the current format didn't yet annoy me enough to
> transfer it.
>
>> What we could do is to build a sample and go over it.
>> Ideally I would like to have formatting as you type :).
> Even something simple like automatic "format-on-save" (optionally)
> would help IMHO.

Yes if you send code we will add it because I would like to give a try
>
> Especially as the format hotkey doesn't work reliably on Mac OS X -
> still have to chase why.

Yes I would like to have.

On 29/12/14 14:32, stepharo wrote: As far as I remember it was just the stock RB(Configurable?)Formatter
with custom settings. Let me dig out my Dolphin Image.

As far as I remember it was just the stock RB(Configurable?)Formatter
with custom settings. Let me dig out my Dolphin Image.

This is the same in Pharo. Lukas improved it.

> On 29 Dec 2014, at 15:30, stepharo <[hidden email]> wrote:
>
> As far as I remember it was just the stock RB(Configurable?)Formatter with custom settings. Let me dig out my Dolphin Image.
>
> This is the same in Pharo. Lukas improved it.

I think the “too many line breaks” is actually a bug. It adds line breaks where it should not.