/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 21:07:32 UTC
  • Revision ID: git-v1:28c2b64490ca54b6152853791a389fdce31e62c5
Added FILE NAME to scripts missing it,
and added FIXME to mp32opus.sh.

Genaral tiying up of desriptor comment

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