Frontier Software

Robert Laing's programing notes

Structured Comments

By Robert Laing

How To Design Programs calls the second step in its recipe “Signature, Purpose Statement, Header”, which ties into what to write in the comments above code to get JSDoc, EDoc, … , *Doc, to produce HTML reference pages.

Signature

Racket

A function signature is a comment that tells the readers of your design how many inputs your function consumes, from which classes they are drawn, and what kind of data it produces. — How To Design Programs

The first edition of How To Design Programs used contract instead of signature, presumably a nod to Design by Contract, a trademarked methodology owned by Eiffel Software.

Erlang calls its signatures specifications, a word I used to summarise the starting point of the design recipe.

Some Racket examples of function signatures from the textbook include

; String -> Number
...

; Number String Image -> Image
...

; WorldState -> Image
...

; PositiveNumber -> String
...

; TrafficLight -> TrafficLight
...

; List-of-numbers -> List-of-numbers
...

The signature tells the reader how many input arguments a function has and their type, and the type of what the function returns. A rule that applies to any programming language is the more specific the better. If a type that isn’t built into the language is used, it is expected to be preceded by a data definition along the lines:

; A Temperature is a Number. 
; interpretation represents Celsius degrees

Erlang

One of the things I like about Erlang is its Types and Function Specifications support.

-spec Module:Function(ArgType1, ..., ArgTypeN) -> ReturnType.

These statements don’t just help EDoc, but another tool called Dialyzer uses it to find type errors along with dead code.

Erlang uses specification as a synonym for signature.

Last updated on 2 Jan 2021
Published on 2 Jan 2021

Content Footer