FriCAS Maths Program - Draft SPAD Style Guide

SPAD does not always have a canonical form. This gives programmers freedom to format code in different ways, this can help make code clearer in different situations. However in the case of the library code it helps readability to have a consistent style across the whole library.

The rules on these things seem to evolve over time but I have not seen them written down in one place. So here is my attempt to do so - along with my views and questions which may be controversial.

Regardless of what's decided, it might be helpful to have it written down in one place where it might be seen by potential programmers.

Whitespace around punctuation

Maximum Line Length

No firm rule but about 70 characters unless that causes problems? I think this is to make it easier to work with files, for instance merging with kdiff3.

Block Indentation

4 characters (no tabs)

Personally I would prefer 2-space indents rather than 4.

The combination of the above 3 rules seems to make line wrapping much more common. I prefer code to be compact rather than have lots of whitespace. I find it is much easier to understand a function if it all fits on my screen at once.

I would therefore prefer not to have unnecessary whitespace added.

Continuation Lines

I prefer explicit '_' even when not required. This makes it clear to the reader that the line has been wrapped.

Function signature

I prefer explicit types, that is:

func(a:Integer) : Integer ==

rather than:

func(a) ==

This is because it avoids having to jump between function export and definition to get all information about it. I like to have all information all in one place.

Empty list

use []$T rather than empty()$T

=>

Which is better:

e := (v > 0 => 1; -1)

vs.

e := if v > 0 then 1 else -1

I find the second much more readable, is it less efficient than the first?

Dangling 'else'

If there is space then the best option is all on one line:

  if .... then .... else ....

Otherwise it should be like this:

  if .... then
      ....
  else
      ....
Or is this a valid option?

  if ....
      then ....
      else ....

elt vs. qelt

I prefer better error messages over speed.

_= vs. "="

When to use:

_=(a : %, b : %) : Boolean ==

or should I use:

"="(a : %, b : %) : Boolean ==

reverse vs. reverse!

Even if it harms performance I would prefer non-mutable option. Surely it would have to be a very long list for the longer time to be noticeable.

Function size

One big function or lots of small (local) functions?

Function Application Parenthesis

For one argument function, "f(a)" vs. "f a", which is better?


metadata block
see also:
Correspondence about this page

Book Shop - Further reading.

Where I can, I have put links to Amazon for books that are relevant to the subject, click on the appropriate country flag to get more details of the book or to buy it from them.

flag flag flag flag flag flag Axiom Volume 1: Tutorial. Documentation is freely availible from: http://www.axiom-developer.org/axiom-website/documentation.html

 

This site may have errors. Don't use for critical systems.

Copyright (c) 1998-2017 Martin John Baker - All rights reserved - privacy policy.