#2815 BuildingFit Fantom Style Guide

Jay Herron Tue 10 Nov 2020

Hey everyone,

BuildingFit has decided to publish our Fantom language Style Guide as a community resource. We use it internally across all our projects, and have found it very beneficial. It's publicly available here, so feel free to use it for your own Fantom projects or provide any feedback.

Thanks!

SlimerDude Tue 10 Nov 2020

Hi Jay,

I've just been flicking through it, it looks really good - a lot of work has gone into it!

I admit that I, myself, take more shortcuts than the guide allows. :/

5.2.3 Constant names

But what is a constant, exactly?

Love it! Over time I've found that I rarely care if a field is constant or not, so I stopped the UPPERCASE convention. But I guess it helps to know how to properly reference static fields.

4.8.8 Explicit function calling

Even if no parameters are needed to be passed to a function, always include parentheses to indicate that this is a function call as opposed to a variable reference.

val.toStr() // Acceptable

val.toStr // NOT acceptable

If a method takes no arguments, then is it actually distinguishable from a field? I really like that Fantom does not care about this. Though I do find I add brackets() if the method is an action, rather than just a calculated getter - to make it clear side-effects are involved.

val.someValue      // field or method - do I care?
val.doSomething()  // actionable method with side effects

But that convention is a little more ambiguous and nebulas to follow.

Amyway, I'll not start any style wars... Thanks for sharing - I'll be sure to distribute!

Jay Herron Tue 10 Nov 2020

Thanks! We owe a ton to the Google java style guide we used as a template (including that line about constants).

I admit that I, myself, take more shortcuts than the guide allows. :/

Yeah, it takes a bit of a hard line on some popular Fantom syntax (like requiring explicit typing, and lambda parentheses, for example). But I think the resulting consistency is worth it, especially when there are multiple developers working on a project.

If a method takes no arguments, then is it actually distinguishable from a field?

That's an excellent point. My reasoning really is the same as yours - I like to be explicit about whether I expect side effects, although that's maybe not a super valuable distinction in the scheme of things.

Thanks again for your feedback Steve!

Henry Wed 11 Nov 2020

Hi Jay,

As a relative newcomer to Fantom it's interesting to see the formatting choices for code in other organisations! (Though I require sticking to the Steve Eynon format!)

I did have one thing of note to perhaps suggest after reading through these which pertains to the section 6.1 regarding exceptions.

Exception: In tests, a caught exception may be ignored without comment if its name is or begins with expected. The following is a very common idiom for ensuring that the code under test does throw an exception of the expected type, so a comment is unnecessary here.

try {
  emptyStack.pop()
  fail()
} catch (NoSuchElementException expected) {
}

We at Fantom Factory prefer to use either the verifyErr() or verifyErrMsg() functions provided in the Test class to test for exceptions, as it's a little more succinct and perhaps more obvious at a glance as to what it's testing

verifyErr(NoSuchElementException#) { emptyStack.pop() }

All in all an interesting read! It's also good to be able to put some names to a few of the notations I've been taught!

Jay Herron Wed 11 Nov 2020

Awesome point, Henry! I'm going to change this - we also use verifyErr internally, I must have just missed that when going through. Thanks!!

brian Wed 11 Nov 2020

This is really nice Jay. Thanks for sharing. If you haven't seen it, the key stuff we use in our own code is documented under docLang::Conventions.

Couple notes where we do things differently:

  • We use Allman style braces which is opposite of most of the Java/JavaScript world these days
  • We always put everything non-test related under fan (for example we use fan/ui/ for UI code)
  • We definitely put multiple classes into one .fan file (that one is a weird Java limitation, which I was glad to get rid of)
  • We never use screaming caps (like Java uses for constants)
  • We always leave off () for no arg methods; and will often switch b/w fields and methods during refactoring. This is an Eiffel principle which I really like (uniform access principle)

Jay Herron Thu 12 Nov 2020

Thanks Brian! I have seen the conventions page and really like how succinct it is! We just wanted to flesh out a few more specific constructions and make some small alterations. That is a great summary of the differences (I actually just removed the ui folder section - that was a misunderstanding). I appreciate the insight into why certain conventions were chosen!

Login or Signup to reply.