100 lines
6.4 KiB
Java
100 lines
6.4 KiB
Java
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE script:module PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "module.dtd">
|
|
<script:module xmlns:script="http://openoffice.org/2000/script" script:name="_CodingConventions" script:language="StarBasic" script:moduleType="normal">REM =======================================================================================================================
|
|
REM === The ScriptForge library and its associated libraries are part of the LibreOffice project. ===
|
|
REM === Full documentation is available on https://help.libreoffice.org/ ===
|
|
REM =======================================================================================================================
|
|
|
|
'''
|
|
' Conventions used in the coding of the *ScriptForge* library
|
|
' -----------------------------------------------------------
|
|
'''
|
|
' Library and Modules
|
|
' ===================
|
|
' * Module names are all prefixed with "SF_".
|
|
' * The *Option Explicit* statement is mandatory in every module.
|
|
' * The *Option Private Module* statement is recommended in internal modules.
|
|
' * A standard header presenting the module/class is mandatory
|
|
' * An end of file (eof) comment line is mandatory
|
|
' * Every module lists the constants that are related to it and documented as return values, arguments, etc.
|
|
' They are defined as *Global Const*.
|
|
' The scope of global constants being limited to one single library, their invocation from user scripts shall be qualified.
|
|
' * The Basic reserved words are *Proper-Cased*.
|
|
'''
|
|
' Functions and Subroutines
|
|
' =========================
|
|
' * LibreOffice ignores the Private/Public attribute in Functions or Subs declarations.
|
|
' Nevertheless the attribute must be present.
|
|
' Rules to recognize their scope are:
|
|
' * Public + name starts with a letter
|
|
' The Sub/Function belongs to the official ScriptForge API.
|
|
' As such it may be called from any user script.
|
|
' * Public + name starts with an underscore "_"
|
|
' The Sub/Function may be called only from within the ScriptForge library.
|
|
' As such it MUST NOT be called from another library or from a user script,
|
|
' as there is no guarantee about the arguments, the semantic or even the existence of that piece of code in a later release.
|
|
' * Private - The Sub/Function name must start with an underscore "_".
|
|
' The Sub/Function may be called only from the module in which it is located.
|
|
' * Functions and Subroutines belonging to the API (= "standard" functions/Subs) are defined in their module in alphabetical order.
|
|
' For class modules, all the properties precede the methods which precede the events.
|
|
' * Functions and Subroutines not belonging to the API are defined in their module in alphabetical order below the standard ones.
|
|
' * The return value of a function is always declared explicitly.
|
|
' * The parameters are always declared explicitly even if they're variants.
|
|
' * The Function and Sub declarations start at the 1st column of the line.
|
|
' * The End Function/Sub statement is followed by a comment reminding the name of the containing library.module and of the function or sub.
|
|
' If the Function/Sub is declared for the first time or modified in a release > initial public release, the actual release number is mentioned as well.
|
|
'''
|
|
' Variable declarations
|
|
' =====================
|
|
' * Variable names use only alpha characters, the underscore and digits (no accented characters).
|
|
' Exceptionally, names of private variables may be embraced with `[` and `]` if `Option Compatible` is present.
|
|
' * The Global, Dim and Const statements always start in the first column of the line.
|
|
' * The type (*Dim ... As ...*, *Function ... As ...*) is always declared explicitly, even if the type is Variant.
|
|
' * Variables are *Proper-Cased*. They are always preceded by a lower-case letter indicating their type.
|
|
' With next exception: variables i, j, k, l, m and n must be declared as integers or longs.
|
|
' > b Boolean
|
|
' > d Date
|
|
' > v Variant
|
|
' > o Object
|
|
' > i Integer
|
|
' > l Long
|
|
' > s String
|
|
' Example:
|
|
' Dim sValue As String
|
|
' * Parameters are preceded by the letter *p* which itself precedes the single *typing letter*.
|
|
' In official methods, to match their published documentation, the *p* and the *typing letter* may be omitted. Like in:
|
|
' Private Function MyFunction(psValue As String) As Variant
|
|
' Public Function MyOfficialFunction(Value As String) As Variant
|
|
' * Global variables in the ScriptForge library are ALL preceded by an underscore "_" as NONE of them should be invoked from outside the library.
|
|
' * Constant values with a local scope are *Proper-Cased* and preceded by the letters *cst*.
|
|
' * Constants with a global scope are *UPPER-CASED*.
|
|
' Example:
|
|
' Global Const ACONSTANT = "This is a global constant"
|
|
' Function MyFunction(pocControl As Object, piValue) As Variant
|
|
' Dim iValue As Integer
|
|
' Const cstMyConstant = 3
|
|
'''
|
|
' Indentation
|
|
' ===========
|
|
' Code shall be indented with TAB characters.
|
|
'''
|
|
' Goto/Gosub
|
|
' ==========
|
|
' The *GoSub* … *Return* statement is forbidden.
|
|
' The *GoTo* statement is forbidden.
|
|
' However *GoTo* is highly recommended for *error* and *exception* handling.
|
|
'''
|
|
' Comments (english only)
|
|
' ========
|
|
' * Every public routine should be documented with a python-like "docstring":
|
|
' 1. Role of Sub/Function
|
|
' 2. List of arguments, mandatory/optional, role
|
|
' 3. Returned value(s) type and meaning
|
|
' 4. Examples when useful
|
|
' 5. Eventual specific exception codes
|
|
' * The "docstring" comments shall be marked by a triple (single) quote character at the beginning of the line
|
|
' * Meaningful variables shall be declared one per line. Comment on same line.
|
|
' * Comments about a code block should be left indented.
|
|
' If it concerns only the next line, no indent required (may also be put at the end of the line).
|
|
'''
|
|
</script:module> |