Next Previous

Changes to "Rationale" between 2018-07-03 20:17:08 and 2018-07-04 01:30:27

︙
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

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








-
+









-
+


-
+




-
+




-
+




-
+




-
+


-
+





-
+




-
+

-
+


-
+















-
-
+
+




-
+

-
+

-
+








## Design Rationale

To make this suitable across programming languages, the syntax needed to
be generic and not be tied to specific docblock variants.

  *  Hence a consecutive `#` block is recommended as default comment style.

        *  Individual implementations are encouraged to support any alternative
       *  Individual implementations are encouraged to support any alternative
           comment block syntaxes.

  *  `key: value` fields are a rather obvious choice. And they're already
     used in related specs (PKG-INFO, Debian control, etc.)


  *  Key names should be single `words:`, or RFC `message-header:` combinations
     at most.

        *  They should never contain spaces, as that made it really cumbersome
       *  They should never contain spaces, as that made it really cumbersome
           to parse/process. (→ And that's how you get ants!)

        *  In some languages it's a rather unfortunate idiom to use "ASCII art"-style
       *  In some languages it's a rather unfortunate idiom to use "ASCII art"-style
           comments. Often there's all sorts of personal variations like
           "Written by:" or "Authored by:" and so on - due to lack of standardization
           and language ecosystem.

        *  Which is precisely what the PMD spec is meant to help against.
       *  Which is precisely what the PMD spec is meant to help against.

  *  All basic fields are suitable to CLI tools, as well as GUI applications, or
     web apps.

        *  Additions like `icon:` etc. can be used for more specific cases.
       *  Additions like `icon:` etc. can be used for more specific cases.

  *  `type:` is one recommended way to support the more widespread "hook" or
     service locator systems.

        *  Albeit even `category:` or custom fields can be fitted for more complex needs.
       *  Albeit even `category:` or custom fields can be fitted for more complex needs.

  *  Utilizing PMD does not require *each and every* source script to carry a meta data
     block.

        *  Obviously it's only meant to augment those code bits that represent
       *  Obviously it's only meant to augment those code bits that represent
           features or extensions.

        *  Though, of course; once you start classifying scripts, or have a huge
       *  Though, of course; once you start classifying scripts, or have a huge
           enough codebase - plugin meta data will appear even in core files.
           (And I'd usually tag them as such - `type: core`)

  *  "Modules" are not scope of this spec.

        *  Of course, for "module packages", one could elect a primary/invocation
       *  Of course, for "module packages", one could elect a primary/invocation
           script, add plugin meta data only there, and leave the rest undocumented.

  *  Another essential feature of PMD is a common [config:](wiki/config) scheme.

        *  Many times plugins themselves represent just settings/adaptions.
       *  Many times plugins themselves represent just settings/adaptions.

        *  For more complex code it's very common to introduce new global application
       *  For more complex code it's very common to introduce new global application
           settings.

        *  Rather than leave each plugin to also micromanage an UI for settings those,
       *  Rather than leave each plugin to also micromanage an UI for settings those,
           defining a standard way to collect options (globally or on per-plugin basis)
           is a neat gimmick.


## Inspired by

Both syntax and usage didn't come out of thin air. There's lots of prior art
and things PMD tries to be compatible with to some extend:

  *  Standard field names mostly come from the Debian packaging spec.
     Which is sort of a standard already. (No need for NIH field names.)

  *  One of the few things Wordpress got right (almost). They've been using
     (or rather inherited) a similar comment-based plugin description scheme.

       *  Except for the abhorrent spaced key names, and not knowing what else to do with it.
       *  Most WP plugins have to define config hooks/settings/handling themselves
      *  Except for the abhorrent spaced key names, and not knowing what else to do with it.
      *  Most WP plugins have to define config hooks/settings/handling themselves
          to this day.

  *  There's a few similar language-specific meta data schemes:

       *  JS userscripts use a constrained docblock-style scheme for similar purposes.
      *  JS userscripts use a constrained docblock-style scheme for similar purposes.

       *  TCL, teapot?
      *  TCL, teapot?
 
       *  ...  (readd from old list...)
      *  ...  (readd from old list...)


## Why not?

Before PMD came to be, I've also tried a couple of common mishaps:

**Meta-data in code**:
︙