=pod

=encoding utf8

=head1 NAME

Muldis::D::Conventions -
Style and design guidelines for Muldis D

=head1 VERSION

This document is Muldis::D::Conventions version 0.2.0.

=head1 PREFACE

This document is part of the Muldis D language specification, whose root
document is L<Muldis::D>; you should read that root document
before you read this one, which provides subservient details.

=head1 DESCRIPTION

This document briefly outlines various conventions used in the Muldis D
language, and provides some style and design recommendations for code
and/or projects written in Muldis D, or for alternate language dialects, or
extensions, or implementations.

Unlike the rest of the Muldis D language specification, following anything
stated herein is not necessary for conformation to the spec, and you should
feel free to break these suggestions whenever it makes sense, just like
when using any style rules.

This document is very much an early draft, and for not just contains a bit
of brainstorming in point form.

=head1 GUIDELINES

=head2 Entity Naming

Note that any use of the word "name" specifically refers to a C<Cat.Name>,
or in other words the declared unqualified name of an entity, which
sometimes is always used in that form, and which other times forms an
element of a C<Cat.NameChain>.

Although Muldis D allows names to be comprised of any characters at all,
and hence they are used delimited in the general case, it is highly
recommended to use only characters in names that are valid for identifier
names in most programming languages, and that are part of the 7-bit ASCII
repertoire, such as C<[a-zA-Z0-9_]>, and that the first character of a name
isn't a digit; that way, it would be easy to support Muldis D dialects
where names are allowed to be non-delimited, as well as more easily permit
translation of Muldis D code into other programming languages while making
fewer changes.  Or if your system is Unicode-saavy (Perl 6 for example),
then the recommendation can be broadened to allow the word characters of
any script, but names should still avoid including whitespace and
punctuation characters.

Type names should all be nouns, or nouns plus adjectives of said, and be
named after what a value of that type I<is>; eg, for any given value Foo of
type Bar, you can say "Foo is a Bar".

Type names should have all of their words capitalized (first letter of each
word is uppercase, other letters of each word are lowercase.  It is
suggested that the words directly adjoin each other without separator
characters, but use of separators is also fine.  In other words, see the
convention for Perl package names, perhaps aka camel case.  But if the type
name includes acronyms, then the acronym should be all uppercase, and where
necessary, multiple acronyms or abbreviations would then often be
underscore-separated.  For examples, C<Int> or C<RatRoundRule>.

Function routine names should all be nouns, and be named after the meaning
of what they result in; also, function parameters should all be nouns, and
be named after the meaning of what they convey to the functions.  For
example, the integer C<difference> function results in the difference when
its C<subtrahend> argument is subtracted from its C<minuend> argument.
Every invocation of a function in Muldis D denotes a value, just like any
program literal, and it is helpful for it to be named accordingly.  A
function name should never be a verb, as a function does not take an action
or I<do> something or have a side-effect; its invocation I<is> something.
Likewise, all named expression names should be nouns.

For a boolean-resulting function, the function name typically is best the
text of a question whose answer is just I<yes> or I<no>; for example,
C<is_identical> or C<is_a_member>.  While not a noun per se, such names
indicate that the meaning of the function's result is the answer of the
question as applied to the function's arguments.

For functions that are best described as deriving Foo from Bar, such as
between numbers and strings, they should be named with the result coming
first in the name and the input coming second, like Foo_from_Bar; do not
use names like Bar_to_Foo.  If the convention of prefix/polish notation is
also followed, then each part of the function's name is next to what it is
describing (output closer to output, input to input, etc), not opposite.

Procedure and updater routine names, by contrast, should all be verbs, and
be named after what action they take, because their invocation I<does> do
something and/or has a side-effect, and does I<not> denote a value.  For
example, C<throw> or C<try_catch>.  Their parameters should be nouns as per
function routines.  Their variables should also be nouns.

If a routine has just one main parameter, and/or the routine could be
conceived as a method for an object that is that argument, and there isn't
already a good name for the parameter, then C<topic> is a good name to
default to; it says that this argument is the topic that the routine is
most concerned with, as per what C<$_> means to Perl (a topicalizer).

All routine names should have their words separated by underscores, and
they generally should be entirely lowercase.  The main exception to this is
if the routine name embeds a type name, in which case the type should be
spelled with its normal casing, such as C<Int_from_Text>.

=head2 Syntax Ordering

Muldis D internally (that is, in the system catalog) organizes parts of
syntax by name rather than by order, so in that respect the language is not
specifically prefix/polish or postfix/reverse-polish or infix or circumfix,
and a Muldis D dialect can take any of those forms or mix them.  You can
even write your code right-to-left if you want, assuming a compatible
parser.

That said, the recommended convention is to use prefix/polish notation
conceptually, or actually if the dialect makes a distinction.  So for
example, in a value expression, the result comes out on the left side and
the inputs go in on the right side.  At least this is assuming you normally
read left-to-right.  But even if you don't, practically all programming
languages are oriented left-to-right anyway, and we can follow that.

=head1 SEE ALSO

Go to L<Muldis::D> for the majority of distribution-internal
references, and L<Muldis::D::SeeAlso> for the majority of
distribution-external references.

=head1 AUTHOR

Darren Duncan (C<perl@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

This file is part of the formal specification of the Muldis D language.

Muldis D is Copyright © 2002-2008, Darren Duncan.

See the LICENSE AND COPYRIGHT of L<Muldis::D> for details.

=head1 TRADEMARK POLICY

The TRADEMARK POLICY in L<Muldis::D> applies to this file too.

=head1 ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in L<Muldis::D> apply to this file too.

=cut
