/useful/trunk-1

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/useful/trunk-1

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: Gustav Hartvigsson
  • Date: 2021-01-13 22:04:57 UTC
  • Revision ID: git-v1:389864e4bf14d1134938a7c731fbbc713ac59cfd
Started working on the HACKING documentation.

Show diffs side-by-side

added added

removed removed

Lines of Context:
HACKING
 
1
General Rules for Contributions and Style Guide
 
2
===============================================
 
3
 
 
4
This document is provided to help keep the scripts provided by this
 
5
branch/repository a consistent style for ease of reading and ease of hacking.
 
6
 
 
7
Structure
 
8
=========
 
9
 
 
10
All scripts in this repository should follow the following structure, it is not
 
11
set in stone or a hard requirement, but it is a good idea for the contributor
 
12
(or hacker) to follow.
 
13
 
 
14
For example take this hypothetical script as an example, but please use already
 
15
existing scripts as a base for new scripts:
 
16
 
 
17
```
 
18
#!/usr/bin/env bash
 
19
#####
 
20
# FILE NAME: my_script.sh
 
21
#
 
22
# Provides a hypothetical example.
 
23
#
 
24
# Changes
 
25
# 2021-01-01:
 
26
#   * Some hypothetical change.
 
27
#
 
28
#####
 
29
 
 
30
 
 
31
__MY_FLAG=0
 
32
__MY_LIST=()
 
33
__MY_STRING=""
 
34
 
 
35
function __usage () {
 
36
  echo ""
 
37
  echo "my_script.sh [options]
 
38
  echo ""
 
39
  echo "  A short description of what this hypothetical script does."
 
40
  echo ""
 
41
  echo "  -h"
 
42
  echo "  --help             Display this help message."
 
43
  echo ""
 
44
  # more arguments
 
45
  echo ""
 
46
}
 
47
 
 
48
function __parse_args () {
 
49
  # arguments parsing code here
 
50
}
 
51
 
 
52
# other functions here
 
53
 
 
54
function __main () {
 
55
  # The main body of the
 
56
  # call other functions depending on the flags if needed.
 
57
}
 
58
 
 
59
__parse_args "${@}"
 
60
__main
 
61
```
 
62
 
 
63
Bellow the different parts of the script will be discussed.
 
64
 
 
65
Descriptor Comment
 
66
------------------
 
67
 
 
68
The first part of the script is the descriptor comment, it serves three
 
69
functions:
 
70
  1. Document the name of the file/script.
 
71
  2. Describe what the script does in short.
 
72
  3. Provide a changelog of the script.
 
73
 
 
74
All scripts must provide this comment, following the template above.
 
75
 
 
76
Global Variables/Flags
 
77
----------------------
 
78
 
 
79
Global variable must be declared at the start of the script, and the type should
 
80
be declarable from how it is declared, and the type must not change throughout
 
81
the lifetime of the script.
 
82
 
 
83
All global variable must sart with two underlines, and be capitalised.
 
84
 
 
85
Declaring a list:
 
86
```
 
87
__VARIABLE_NAME=()
 
88
```
 
89
 
 
90
Declaring a string:
 
91
```
 
92
__VARIABLE_NAME=""
 
93
```
 
94
 
 
95
Declaring a numerical value/flag:
 
96
```
 
97
__VARIABLE_NAME=0
 
98
```
 
99
 
 
100
Declaring a boolean flag:
 
101
```
 
102
__VARIABLE_NAME=false
 
103
# or
 
104
__VARIABLE_NAME=true
 
105
```
 
106
 
 
107
**Note on boolean values:** Boolean values don't actually exist in the bash
 
108
environment, and are treated as strings by bash. If a true boolean value is
 
109
needed declare use numerical `1` and `0`, or declare `true=1` and `false=0`.
 
110
 
 
111
Use functions as Much as Possible
 
112
---------------------------------
 
113
 
 
114