This repository has been archived by the owner on May 22, 2018. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
248 lines (149 loc) · 8.3 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
--------------------------------------------------------------------------------
Introduction
--------------------------------------------------------------------------------
Halfdecent Sharp is a suite of libraries and tools for .NET software
development.
--------------------------------------------------------------------------------
Libraries
--------------------------------------------------------------------------------
The libraries variously fix, supplement, replace, and extend parts of
the Base Class Library.
- Halfdecent has tuples, intervals, comparables and comparers,
maybes, proxies, and pseudo-pattern matching
- Halfdecent.Resources is a simplified, strongly-typed API for
accessing embedded resources
- Halfdecent.Globalisation has logical localised objects, culture
fallback algorithms, localised string operations, and localisable
exceptions
- Halfdecent.Meta includes references to variables, parameters,
properties, etc. with mechanisms for mapping them across stack
frames, plus exceptions with references to offending values
- Halfdecent.RTypes are reusable, composable value checks
- Halfdecent.Numerics has abstract numeric types and operations
- Halfdecent.Streams has abstract streams, sinks, filters, and
pipelines
- Halfdecent.Cursors are moveable pointers to items in collections
- Halfdecent.Collections has a variety of collections, each with
variations for different combinations of mutability, and
by-reference slices
- Halfdecent.TextTree is a simple text file format that uses
indentation to create structure
- Halfdecent.Testing is a library for writing and running unit
tests
--------------------------------------------------------------------------------
Tools
--------------------------------------------------------------------------------
The tools are lightweight and suited for use from the command line and
scripts.
- Resbian is a tool for working with embedded resources
- Traitor is a C# preprocessor enabling interfaces to carry
implementation code (within a project).
- Permuda is a C# preprocessor that generates multiple similar files
from a single template file
--------------------------------------------------------------------------------
Requirements
--------------------------------------------------------------------------------
- A .NET framework (Microsoft or Mono)
- A Bourne (Unix) shell with standard command-line tools
- GNU Make
- Makery build system (http://github.com/macro187/makery)
--------------------------------------------------------------------------------
Quick Start
--------------------------------------------------------------------------------
1. Get Makery and Halfdecent Sharp
$ cd /my/workspace
$ git clone https://github.com/macro187/makery.git
$ git clone https://github.com/macro187/halfdecentsharp.git
2. Configure Makery
$ export MAKERY=/my/workspace/makery
3. Build everything
$ cd /my/workspace/halfdecentsharp
$ make buildall
4. Test everything
$ make testall
5. If you have Doxygen installed, generate documentation for everything
$ make doxygenall
6. Look in each project's out/ subdirectory for build outputs
7. Clean up
$ make cleanall
--------------------------------------------------------------------------------
Design Principles
--------------------------------------------------------------------------------
Use the Type System
Aggressively push concepts into the static type system, allowing the
compiler to help verify their implementation and usage.
Abstract Types [1]
Prefer defining and referencing abstract types.
Single Responsibility [2]
Make types "fine-grained" with each capturing a single aspect, idea,
or responsibility reduced to its purest form. Aggressively factor
common aspects out into separate types.
Nouns over Verbs
"Even the simplest procedural logic is hard for humans to verify,
but quite complex data structures are fairly easy to model and
reason about... It follows that where you see a choice between
complexity in data structures and complexity in code, choose the
former. In evolving a design, you should actively seek ways to shift
complexity from code to data." [3]
Minimise algorithms and procedures. Prefer introducing new types
over new algorithms. Maximise algorithm reusability by implementing
them in terms of the most general types possible.
Resist Optimisation
"Rule 1. You can't tell where a program is going to spend its time.
Bottlenecks occur in surprising places, so don't try to second guess
and put in a speed hack until you've proven that's where the
bottleneck is.
Rule 2. Measure. Don't tune for speed until you've measured, and
even then don't unless one part of the code overwhelms the rest.
Rule 3. Fancy algorithms are slow when n is small, and n is usually
small. Fancy algorithms have big constants. Until you know that n is
frequently going to be big, don't get fancy. (Even if n does get
big, use Rule 2 first.)
Rule 4. Fancy algorithms are buggier than simple ones, and they're
much harder to implement. Use simple algorithms as well as simple
data structures." [3]
"When in doubt, use brute force." [3]
Worry about making things simple and understandable, not fast.
Don't prevent future optimisation, but don't do it yet.
Source Code Centric
Prefer source code over binaries. Resist additional complexity in
the name of binary compatibility, library versioning or related
concerns. Assume users of the libraries will refer to its source
code regularly in addition to (or in lieu of) other forms of
documentation. Assume users of the libraries are familiar with
version control systems.
Universal
Assume use on various CLR implementations, various operating
systems, various CPU architectures, in software for end users from
various countries speaking various languages.
Be Polite
Allow piecemeal, gradual adoption of the library. Don't force users
to accept the entire worldview at once. Interoperate with the Base
Class Library where possible, even the parts of it that this library
replaces. Avoid seizing control of the program - the user uses the
library, not the other way around. Be a library, not a "framework".
Reduce workload, not control.
These design principles happen to be more or less in line with an
accepted set of object-oriented design principles called SOLID [4].
There are also parallels to be found with The Art of UNIX Programming
[5].
[1] http://en.wikipedia.org/wiki/Abstract_type
[2] http://en.wikipedia.org/wiki/Single_responsibility_principle
[3] http://www.faqs.org/docs/artu/ch01s06.html
[4] http://en.wikipedia.org/wiki/Solid_%28object-oriented_design%29
[5] http://www.faqs.org/docs/artu/
--------------------------------------------------------------------------------
Licence
--------------------------------------------------------------------------------
Copyright (c) 2008-2016
Ron MacNeil <macro187 AT users DOT sourceforge DOT net>
Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.