Difference between revisions of "SMILA/Style Guide"

From Eclipsepedia

Jump to: navigation, search
m (SMILA/Style guide moved to SMILA/Style Guide: Page name conventions)

Revision as of 04:51, 29 September 2008

This document gives the style conventions to be used in the SMILA Wiki. Please follow these guidelines on all SMILA Wiki pages to guarantee similar styles and conventions.

Contents

Pages

Guidelines for the page name:

  • Use a self-explanatory page name.
  • Separate words in the page name by underscores, e.g. "Development_guidelines".
  • Do not use articles (the, a, an) or prepositions (to, for, from) in page names unless they are essential for understanding the context. Example: "Integrate_Components" is a better page name than "Integrate_a_Component_in_SMILA" in case your page is a general description of this topic but "How_to_Integrate_Components" is OK to indicate that your page contains a how-to tutorial.
  • Use title capitalization for page names.


Other guidelines referring to the page:

  • Provide a short description after the page heading that describes the contents of your page. Help the reader to quickly find out the main topic of your page.
  • Provide a table of contents where it is reasonable. This should be applied automatically to your page.
  • Tag your page with the SMILA category: [[Category:SMILA]]

Headings

Guidelines for headings:

  • Do not omit a heading level.
  • Do not use title capitalization for headings, i.e. use uppercase letters for the first letter of the first word in a heading only. Subsequent words are only capitalized if they refer to a proper name.
  • Do not repeat the page name as a heading.

Terminology

Use the spelling and capitalization of SMILA terms as shown on the SMILA glossary. If you term appears not on this page, add it to the glossary, and provide a description (if reasonable). Provide a link to the glossary entry on your page.

Examples

Always provide a short description of your code example. Depending on the example one or two sentences might already be enough. However, the code example alone without a description might not be very helpful.

Images

The same as with examples (see above). Make sure to provide a short description.

Conventions of formats

The following table describes how different text elements should be formatted. Please follow the conventions given.

Element Description Example
Properties Use italics for properties, attributes, and parameters. It converts the document's content defined by the AttachmentContent attribute and stores the plain text results in the AttachmentText attribute.
XML elements Use monospace font for XML elements. The Property element is used to define ...
Filenames Use monospace font for filenames. If you refer to an environment variable use $varname as a reference to the variable. If you refer to the default installation directory, a user's home folder, or another typical folder use a notation in angle brackets to refer to this location in a file name. You will have to use the corresponding HTML entities to escape the angle brackets. Always use the "/" character in paths (not "\" as in Windows). $SMILA_HOME/configuration/xyz

<your-home-directory>/dev/src/xyz

Packages, classes, interfaces, ... Use monospace font for packages, bundles, classes, interfaces and other code elements. org.eclipse.smila.processing.pipelets.aperture
Source Code Use syntax highlighting where possible.
<PipeletConfiguration xmlns="http://www.eclipse.org/eilf/processor">
  <Property name="AttachmentContent">
    <Value>Content</Value>
  </Property>
  <Property name="AttachmentText">
    <Value>Text</Value>
  </Property>
  <Property name="AttachmentMimeType">
    <Value>MimeType</Value>
  </Property>  
</PipeletConfiguration>