-
Notifications
You must be signed in to change notification settings - Fork 46
Naming Conventions
Spacebrew is not a language, but instead a framework. As such, its implementation in various languages should respect the conventions of that language. However, since Spacebrew is a framework mainly for communication, there are some parts of Spacebrew that exist outside any one language's lexical conventions. I am particularly speaking about naming conventions as they affect Client, Publisher, and Subscriber names. At the end I will also suggest naming conventions for Types and best practices for Descriptions.
===
Client names are used primarily by people to identify either services or individual inputs and outputs in the admin interface. As such, their format should facilitate easy scanning, as well as allowing people creating Clients to clearly and concisely state the purpose of the Client. I suggest using space-separated words with the first letter of each word in upper case and the remaining letters in lower case. Peaple naming Clients should strive to keep their Client names consise.
- Flickr
- Twitter Filter
- Quin's Image Viewer
===
Publisher names help tell users about the data being published, while Subscriber names help users understand what will be done with data that is provided to them. When naming a Publisher or Subscriber, remember that users will already see the type of the input/output as well as whether it is an input or an output. These two pieces of information, along with the name of the Client itself, help contextualize the Publisher or Subscriber already. Publisher and Subscriber names should be in all lower case with space-separated words.
- data
- pressed
- remote press
===
Type names are in some ways the most complicated topic. They should use terms that are familiar with programmers. This allows people first learning to use Spacebrew to easily understand generally what a type is when they see the name, and how that relates to whatever programming language they are familiar with. Through necessity, types are linked to specific internal representations, and though terms like "int" are used by many languages to refer to natural numbers, in various languages and on various platforms they have different restrictions.
Spacebrew's type naming has so far been limited to what are commonly referred to as "base types" in other languages. Also borrowing from other languages they have been single words in all lower case alphabetic characters only. As people develop custom types, they should strive to name them using the same convention, however sometimes one word cannot specify a type accurately enough, in these cases you should use an underscore to separate words. Hopefully it is not necessary to ever use more than two words while defining a type, typically the fromat [MODIFIER]_[BASE_TYPE] is sufficient to accurately identify a type when necessary.
- string
- url
- image_url
- base64_jpg
===
Descriptions help further explain the purpose and functionality of a Client to users. Descriptions should not attempt to fully explain how a Client works or define concepts that may be unfamiliar to users. Descriptions can be formatted as full sentences, but should be no more than 2 sentences in length.