pForth style guide

[Phil Burk]

Greetings pForth developers,

I have noticed that my coding in pForth has been inconsistent. So I have created a proposed Style Guide for code that is part of pForth. This guide only applies to code that is checked into the pForth repository. It does not apply, of course, to your own projects.

This is just a draft. If you are interested in pForth, or in Forth style in general, then feel free to offer feedback.

https://github.com/philburk/pforth/wiki/Style-Guide

Thanks,

Phil Burk

[Helmut Eller]

I have some questions:

• should EXIT be written in uppercase?
  
• is it better to write
  IF nip EXIT THEN
  or 
  IF nip EXIT
  THEN
  
  
• should comments in colon definitions be written like so:
  : foo
      dup
      \ blabla
      frob
  ;
  
  or so
  : foo
      dup
  \ blabla
      frob
  ;
  
  

[Phil Burk]

Hello Helmut,

> should EXIT be written in uppercase?

I think so. It is a major control flow word. If someone didn't notice the EXIT then they might totally misread a word. I know you like using EXIT to bail out of the middle of a word. I think that is OK for limited use, particularly when validating input parameters.

I prefer aligning IF and THEN. But for very short constructs it seems OK to put them on the same line. It's a bit like in 'C':

    if (x < 0) return;

Normally I would prefer using { } but sometimes a one liner is more clear. I don't want to rigid. It is Forth after all. But a little consistency could make the code base look a lot nicer.

I used to put comments in column 1. But now I prefer aligning the comments with the code.

: foo 
    dup
    \ blabla
    frob
;

BTW, thanks for all your recent work on pForth! You've made some significant improvements.

Phil Burk

[Helmut Eller]

On Sun, Jan 01 2017, Phil Burk wrote:

> I don't want to rigid. It is Forth after all. But a little
> consistency could make the code base look a lot nicer.

Thanks for the explanations. It's quite useful to know your rules. I
hope I don't bend the rules too much :-).

> BTW, thanks for all your recent work on pForth! You've made some
> significant improvements.

Thanks for the kind words.

BTW, I think you should enable Travis for pForth. E.g. you can then see
if "make test" fails before you merge a pull request.

Helmut

[Phil Burk]

Hello Helmut,

>  I hope I don't bend the rules too much :-).

No. Your code is great. I'm learning by watching you "bend the rules".

I think Travis is a good idea.

>  E.g. you can then see if "make test" fails before you merge a pull request.

It was passing before you added the t_file.fth tests. I don't like to disable failing tests. But it may be awhile before that whole test passes.

Phil Burk