NAME
Language::MuldisD::Conventions - Style and design guidelines for Muldis D
VERSION
This document is Language::MuldisD::Conventions version 0.0.2.
PREFACE
This document is part of the Muldis D language specification, whose root document is Language::MuldisD; you should read that root document before you read this one, which provides subservient details.
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.
GUIDELINES
Entity Naming
Note that any use of the word "name" specifically refers to a 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 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 [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 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. If the type is an enumerated type, it is suggested that the name start with E_ to help documentation, but there are also many situations not to do this in (eg, Bool). For examples, Int or RatRoundRule or E_ENK.
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 difference function results in the difference when its subtrahend argument is subtracted from its 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 do something or have a side-effect; its invocation 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 yes or no; for example, is_identical or 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 does do something and/or has a side-effect, and does not denote a value. For example, throw or 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 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 $_ 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 Int_from_Text.
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.
SEE ALSO
Go to Language::MuldisD for the majority of distribution-internal references, and Language::MuldisD::SeeAlso for the majority of distribution-external references.
AUTHOR
Darren Duncan (perl@DarrenDuncan.net)
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 Language::MuldisD for details.
ACKNOWLEDGEMENTS
The ACKNOWLEDGEMENTS in Language::MuldisD apply to this file too.