commit ff18a47c579f3b294a9159ff69b4b2db465f46a6
Author: krasjet
Date: 2020-12-22 08:21Z
init
Diffstat:
| A | README | | | 57 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 57 insertions(+), 0 deletions(-)
diff --git a/README b/README
@@ -0,0 +1,57 @@
+mwe
+===
+
+I love code examples that are minimal, complete, useful, hackable, and, most
+importantly, correct. I call them *minimal working examples* (MWE).
+
+In particular, a minimal working example should be
+
+1. Minimal
+ Not necessarily capped at certain sloc, but every line should contribute to
+ the meaning of the program.
+2. Complete
+ It can compile without warnings with
+
+ -Wall -Wextra -pedantic
+
+ flags turned on. Errors and exceptions should be handled properly.
+3. Useful
+ It can be used as a component in a real-world program with trivial
+ modifications.
+4. Hackable
+ Modifications and explorations should be encouraged. The code example
+ should compile without noticeable delay and it should be easy to extend the
+ example with custom functionalities.
+5. Correct
+ The program should work as intended on valid inputs and valgrind should be
+ clean unless a fatal error occurs. No memory leaks should be possible.
+
+Many people seem to restrict the use of this term to describe the preferred
+code style for bug reports, but I hope more developers could adopt this style
+to document library functions. Sometimes a minimal working example can be more
+useful than paragraphs of explanations describing what a function do.
+
+I have written many such examples scattered on my hard drive while playing with
+libraries and frameworks. I figure it might be helpful if make them public, as
+I noticed many libraries tend to have poor documentations, at least from my
+perspective.
+
+I'll need to review the code examples to make sure they are really *minimal*
+and *working*, so the release process can take some time. Be patient and good
+luck exploring.
+
+Build
+-----
+
+In each subdirectory, run
+
+ $ make
+
+to compile the examples.
+
+Further reading
+---------------
+
+- Linux Programmer's Manual: man-pages(7)
+- SSCCE: http://sscce.org/
+- doctest: https://docs.python.org/3/library/doctest.html
