Anatomy of a function

A function is simply a processing machine that will take an input and massage/manipulate/calculate and return the result as an output. Wikipedia defines it as:

In computer programming, a subroutine is a sequence of program instructions that perform a specific task, packaged as a unit. This unit can then be used in programs wherever that particular task should be performed. Subprograms may be defined within programs, or separately in libraries that can be used by multiple programs.*

In different programming languages a subroutine may be called a procedure, a function, a routine, a method, or a subprogram. The generic term callable unit is sometimes used. ¹

In the case of Sass, the goal of a function remains the same. The manipulation of input value(s) resulting in the return of the desired value. A simple example of a function is the following 'em' calculator:

$default-browser-font-size: 16px !global;

// A function that calculates the em value of a pixel
// size based on the default font size for the browser
// or the root element

@function emCalculator($size, $context: $default-browser-font-size) {
  @return $size / $context * 1em;
}

The general anatomy of a function in Sass is as follows:

A function always begins with @function keyword. Parameter(s) for the mixin are not required but it will make the mixin more dynamic if added.

@function [function-name]([function-parameters...]) { ... }

A function can take advantage of @if @else, @for, @each, or @while. Also there can be usage of other functions or mixins within the function.

The end result of the function is a return value in the form of a string or number or variable.

@return [result];

Combined, an example function would look like the following:

@function [function-name]([function-parameters ...]) {
  [function logic/Sass functions]
  @return [result]
}

As you can see, the em calculator function that we created follows along this structure that we have laid out. One rule to follow is to name the function in a descriptive manner. A vague and shortened name will not help other developers understand the reason for the function and as a result it may go unused or misused.

Sometimes the name of a function has been shortened in order to facilitate typing of the function at every use. To help in this matter, we suggest that an overloaded function always accompany the original function that will have a more reasonable name.

@function em($size, $context: $default-browser-font-size) {
  @return emCalculator($size, $context);
}

In the case of our example, we created the emCalculator function and also the overloaded em function. The usage of this function will look something like this:

.container {
  font-size: em(12px);
}

The above code will compile into the following CSS:

.container {
  font-size: 0.75em;
}

Here is a more complex function example:

// ===== Linear gradient color processing =================
//  Function that will process the given number of colors
//  and return the correct color strings as comma separated values
// ========================================================
@function linearGradientColors($stop-colors...) {
  $full: false;
  @each $stop-color in $stop-colors {
    @if $full {
      $full: $full + ',' + $stop-color;
    } @else {
      $full: $stop-color;
    }
  }

  $full: unquote($full);

  @return $full;
}

@function lgc($stop-colors...) {
  @return linearGradientColors($stop-colors...);
}

This function takes a variable arguments ² and returns a comma separated string of values. This is useful so that we are not restricted bby a certain number of parameters, giving us the freedom to use as many necessary parameters.

1. Function definition: http://en.wikipedia.org/wiki/Subroutine
2. Variable arguments: arguments at the end of a mixin or function declaration that take all leftover arguments and package them up as a list. These arguments look just like normal arguments, but are directly followed by ...