| blob | 71fb42c77201d47b86570bfaa30ff3ebe461e3c0 |
3 <script:module xmlns:script="http://openoffice.org/2000/script" script:name="_CodingConventions" script:language="StarBasic" script:moduleType="normal">REM =======================================================================================================================
4 REM === The ScriptForge library and its associated libraries are part of the LibreOffice project. ===
5 REM === Full documentation is available on https://help.libreoffice.org/ ===
6 REM =======================================================================================================================
8 '''
9 ' Conventions used in the coding of the *ScriptForge* library
10 ' -----------------------------------------------------------
11 '''
12 ' Library and Modules
13 ' ===================
15 ' * The *Option Explicit* statement is mandatory in every module.
16 ' * The *Option Private Module* statement is recommended in internal modules.
17 ' * A standard header presenting the module/class is mandatory
18 ' * An end of file (eof) comment line is mandatory
19 ' * Every module lists the constants that are related to it and documented as return values, arguments, etc.
20 ' They are defined as *Global Const*.
21 ' The scope of global constants being limited to one single library, their invocation from user scripts shall be qualified.
22 ' * The Basic reserved words are *Proper-Cased*.
23 '''
24 ' Functions and Subroutines
25 ' =========================
26 ' * LibreOffice ignores the Private/Public attribute in Functions or Subs declarations.
27 ' Nevertheless the attribute must be present.
28 ' Rules to recognize their scope are:
29 ' * Public + name starts with a letter
30 ' The Sub/Function belongs to the official ScriptForge API.
31 ' As such it may be called from any user script.
33 ' The Sub/Function may be called only from within the ScriptForge library.
34 ' As such it MUST NOT be called from another library or from a user script,
35 ' as there is no guarantee about the arguments, the semantic or even the existence of that piece of code in a later release.
37 ' The Sub/Function may be called only from the module in which it is located.
38 ' * Functions and Subroutines belonging to the API (= "standard" functions/Subs) are defined in their module in alphabetical order.
39 ' For class modules, all the properties precede the methods which precede the events.
40 ' * Functions and Subroutines not belonging to the API are defined in their module in alphabetical order below the standard ones.
41 ' * The return value of a function is always declared explicitly.
44 ' * The End Function/Sub statement is followed by a comment reminding the name of the containing library.module and of the function or sub.
45 ' 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.
46 '''
47 ' Variable declarations
48 ' =====================
49 ' * Variable names use only alpha characters, the underscore and digits (no accented characters).
50 ' Exceptionally, names of private variables may be embraced with `[` and `]` if `Option Compatible` is present.
51 ' * The Global, Dim and Const statements always start in the first column of the line.
52 ' * The type (*Dim ... As ...*, *Function ... As ...*) is always declared explicitly, even if the type is Variant.
53 ' * Variables are *Proper-Cased*. They are always preceded by a lower-case letter indicating their type.
54 ' With next exception: variables i, j, k, l, m and n must be declared as integers or longs.
55 ' > b Boolean
56 ' > d Date
57 ' > v Variant
58 ' > o Object
59 ' > i Integer
60 ' > l Long
61 ' > s String
62 ' Example:
63 ' Dim sValue As String
64 ' * Parameters are preceded by the letter *p* which itself precedes the single *typing letter*.
65 ' In official methods, to match their published documentation, the *p* and the *typing letter* may be omitted. Like in:
66 ' Private Function MyFunction(psValue As String) As Variant
67 ' Public Function MyOfficialFunction(Value As String) As Variant
68 ' * Global variables in the ScriptForge library are ALL preceded by an underscore "_" as NONE of them should be invoked from outside the library.
69 ' * Constant values with a local scope are *Proper-Cased* and preceded by the letters *cst*.
70 ' * Constants with a global scope are *UPPER-CASED*.
71 ' Example:
73 ' Function MyFunction(pocControl As Object, piValue) As Variant
74 ' Dim iValue As Integer
76 '''
77 ' Indentation
78 ' ===========
79 ' Code shall be indented with TAB characters.
80 '''
81 ' Goto/Gosub
82 ' ==========
83 ' The *GoSub* … *Return* statement is forbidden.
84 ' The *GoTo* statement is forbidden.
85 ' However *GoTo* is highly recommended for *error* and *exception* handling.
86 '''
87 ' Comments (english only)
88 ' ========
95 ' * The "docstring" comments shall be marked by a triple (single) quote character at the beginning of the line
96 ' * Meaningful variables shall be declared one per line. Comment on same line.
97 ' * Comments about a code block should be left indented.
98 ' If it concerns only the next line, no indent required (may also be put at the end of the line).
99 '''
100 </script:module>