"Fossies" - the Fresh Open Source Software Archive

Member "ponyc-0.33.2/STYLE_GUIDE.md" (3 Feb 2020, 14757 Bytes) of package /linux/misc/ponyc-0.33.2.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "STYLE_GUIDE.md": 0.33.1_vs_0.33.2.

Pony Standard Library Style Guide

This is a document describing the preferred practices for writing code for the Pony standard library. Other projects are free to use the same style, but you are free to use any style in other projects. The following conventions are meant to ensure consistency and readability of Pony code. Any of the following rules may be broken in situations where the recommended practice would diminish readability.

Formatting

Line Length

The maximum line length is 80 columns.

Trailing Whitespace

No trailing whitespace at the end of lines.

Indentation

Use 2 spaces for indentation, no hard tabs.

actor Main
  new create(env: Env) =>
    env.out.print("Hello, world!")

Blank Lines

Whitespace

Type Aliases

Align long union and intersection types with each type on a separate line starting with the (, |, or & symbols. In this case, every symbol must be separated by a single space or a newline.

// OK
type Signed is (I8 | I16 | I32 | I64 | I128)

// OK
type Signed is
  ( I8
  | I16
  | I32
  | I64
  | I128 )

// OK
type Signed is
  ( I8
  | I16
  | I32
  | I64
  | I128
  )

// Not OK
type Signed is ( I8
              | I16
              | I32
              | I64
              | I128 )

// Not OK
type Signed is
  (I8
  |I16
  |I32
  |I64
  |I128)

Array Literals

Multiline arrays generally have a newline between each entry, though logical exceptions exist (such as tables).

// OK
let ns = [as USize: 1; 2; 3]

// OK
let strs = ["a"; "b"; "c"]

// OK
let ns =
  [ as USize:
    1
    2
    3 ]

// OK
let ns =
  [ as USize:
    1
    2
    3
  ]

// Not OK
let ns =
  [as USize:
   1
   2
   3
  ]

// Not OK
let ns = [ as USize:
    1
    2
    3
]

// Not OK
let ns = [ as USize:
          1
          2
          3 ]

Control Structures

Assignment

Assignment of a multiline expression is indented below the = symbol.

// OK
var x =
  if friendly then
    "Hello"
  else
    false
  end

// OK
let output =
  recover String(
    file_name.size()
      + file_linenum.size()
      + file_linepos.size()
      + msg.size()
      + 4)
  end

// Not OK
var x = if friendly then
  "Hello"
else
  false
end

Method Declarations

Function Calls

Type Parameters and Constraints

Multiline type parameters are each listed on a separate line. Type constraints will start on the next line beginning with the is keyword. Complex type constraints follow the rules described in Type Aliases.

// OK
type Map[
  K: (mut.Hashable val & Equatable[K]),
  V: Any #share]
  is HashMap[K, V, mut.HashEq[K]]

// OK
class Flags[
  A: Flag[B] val, B: (Unsigned & Integer[B] val) = U64]
  is Comparable[Flags[A, B] box]

// OK
type BinaryHeapPriority[A: Comparable[A] #read]
  is ( _BinaryHeapPriority[A]
    & (MinHeapPriority[A] | MaxHeapPriority[A]) )

// OK
fun ref zip4[B, C, D, E](
  i2: Iterator[B],
  i3: Iterator[C],
  i4: Iterator[D],
  i5: Iterator[E])
  : Iter[(A, B, C, D, E)]^
=>

// OK
fun div_checked[
  T: (SignedInteger[T, U] val & Signed),
  U: UnsignedInteger[U] val](
  x: T,
  y: T)
  : (T, Bool)
=>

// Not OK
primitive HashEq64
  [A: (Hashable64 #read & Equatable[A] #read)] is HashFunction64[A]

// Not OK
class Flags[A: Flag[B] val,
            B: (Unsigned & Integer[B] val) = U64]
  is Comparable[Flags[A, B] box]

// Not OK
class val _MapCollisions[K: Any #share, V: Any #share,
  H: mut.HashFunction[K] val]

// Not OK
fun mod_checked
  [T: (SignedInteger[T, U] val & Signed), U: UnsignedInteger[U] val](
  x: T,
  y: T)
  : (T, Bool)
=>

Naming

Documentation

Public functions and types must include a triple-quoted docstring unless it is self-explanatory to anyone with the most basic knowledge of the domain. Markdown is used for formatting. The """ tokens are placed on their own lines, even when the entire docstring could fit on a single line with the """ tokens.

primitive Format
  """
  Provides functions for generating formatted strings.
  * fmt. Format to use.
  * prefix. Prefix to use.
  * prec. Precision to use. The exact meaning of this depends on the type,
  but is generally the number of characters used for all, or part, of the
  string. A value of -1 indicates that the default for the type should be
  used.
  * width. The minimum number of characters that will be in the produced
  string. If necessary the string will be padded with the fill character to
  make it long enough.
  * align. Specify whether fill characters should be added at the beginning or
  end of the generated string, or both.
  * fill: The character to pad a string with if is is shorter than width.
  """

Comments

Single line comments will have exactly one space between the // token and the beginning of the comment message. This single space may only be omitted if the comment only contains valid Pony code. Single line comments that continue a previous comment have the same spacing requirements. No such restrictions are placed on multiline comments between the /* and */ tokens.

// if `data` is 1 cacheline or less in size
// copy it into the existing `_current` array
// to coalesce multiple tiny arrays
// into a single bigger array