matthiasbeyer/imag
1
0
Fork 0
Code Releases Activity

Update conventions

Browse source
This commit is contained in:
Matthias Beyer 2018-06-11 20:31:14 -03:00
parent f9294eb07a
commit 6e45727f15
1 changed files with 14 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
doc/src/03010-conventions.md
View file

@ -43,23 +43,24 @@ cross-read it for better understanding of the imag project.
### Library naming ### Library naming
Libraries which provide functionality for entries or the store (most likely Libraries which provide functionality for entries or the store but no
entries or both) should be named "libimagentrything" whereas "thing" stands for domain-functionality should be named "libimagentrything" whereas "thing" stands for
what the library provides. what the library provides.
All other libraries should be prefixed with "libimag" at least. Most likely, one All domain libraries should be prefixed with "libimag".
will not write such a library but rather a "libimagentrything" library.
### Library scope ### Library scope
A library should never introduce utility functionality which could be useful for A library should never introduce utility functionality which could be useful for
other libraries as well. If there is no such functionality available, the other libraries as well. If there is no such functionality available, the
"libimagutil" or "libimagentryutil" might be a place where such a function "libimagutil" or "libimagentryutil" might be a place where such a function
would be put. would go to.
If a library has to introduce free functions in its public interface, one should If a library has to introduce free functions in its public interface, one should
think hard whether this is really necessary. think hard whether this is really necessary.
### Library error types/kinds ### Library error types/kinds
Libraries must use "error-chain" to create error types and kinds. Libraries must use "error-chain" to create error types and kinds.
@ -72,6 +73,7 @@ as many error kinds as required.
### Libraries with commandline frontends ### Libraries with commandline frontends
Libraries with commandline frontends provide end-user functionality. Libraries with commandline frontends provide end-user functionality.
They are called "domain" libraries.
Normally, Normally,
they depend on one or more "libimagentrything" libraries. They should be named they depend on one or more "libimagentrything" libraries. They should be named
"libimagthing", though. For example: "libimagdiary", "libimagtimetrack" or "libimagthing", though. For example: "libimagdiary", "libimagtimetrack" or
@ -83,8 +85,6 @@ If such a library needs to depend on another "libimagthing", for example if
whether the functionality could be outsourced to a more general whether the functionality could be outsourced to a more general
"libimagentrything". "libimagentrything".
A library which implements a functionality for imag may contain helper functions
for commandline stuff, but that is discouraged.
### Library testing ### Library testing
@ -96,6 +96,11 @@ possible without a lot of effort, but still: more tests = better!
The commandline tools are the CLI-frontends for their respective libraries. The commandline tools are the CLI-frontends for their respective libraries.
So `libimagdiary` has a CLI frontend `imag-diary`. So `libimagdiary` has a CLI frontend `imag-diary`.
Those CLI frontends use functionality from `libimagrt` to build a consistent Those CLI frontends use functionality from `libimagrt` to build a
commandline interface. commandline interface which is consistent with the rest of the ecosystem.
Commandline interfaces should receive store IDs as positional arguments.
Commandline interfaces should also provide a flag "-I" (that's a big i) which
marks that the store IDs shall be read from stdin and are not passed via the
commandline.