7.1.2. Comentários

Uma boa prática de programação, consiste em documentar as funções. Em PL/pgSQL, os comentários de linha começam com um duplo hífen (--), enquanto comentários de bloco utilizam as marcações /* e */.

O trecho de código abaixo mostra como incluir alguns comentários na definição da função my_distance.

/*
  Descrição: Função que computa a distância euclidiana
             entre dois pontos.

  Parâmetros:
    - first:  Ponto no espaço bidimensional.
    - second: Ponto no espaço bidimensional.

  Retorno: um valor numérico que representa a distância
           euclidiana entre os pontos informados.
 */
CREATE OR REPLACE FUNCTION my_distance(first GEOMETRY, second GEOMETRY)
    RETURNS NUMERIC
    AS
    $$
        DECLARE
            dx NUMERIC DEFAULT 0.0;
            dy NUMERIC DEFAULT 0.0;
            d  NUMERIC DEFAULT 0.0;
        BEGIN
            dx := ST_X(first) - ST_X(second);
            dy := ST_Y(first) - ST_Y(second);

            -- sqrt: operação raiz quadrada
            d := sqrt(power(dx, 2) + power(dy, 2));

            RETURN d;
        END;
    $$
    LANGUAGE plpgsql;