Are there existing rules for creating good modules?

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
The Modules section in the docs explain how they work. But it doesn't very well cover the topic how a good module is documented. I mean, I could look how it's done with other modules. That way I would probably only learn about how a module works fine even if the code to comments ratio is approx ERROR_DIVISION_BY_ZERO

But I'm interested in more:
- Naming conventions (I found capitalisation rules). Like prefixing class names or private fields.
- Conventions for function descriptions / headers (comments).
- How to do a good documentation of your module. Preferably coming with a documentation of .cerberusdoc-file syntax.

TBH I might end up ignoring some of the "rules". I'm fine with stuff like guidelines or even simple examples of beautiful code and docs rather than ultra strict industry-proof standards. It's just to be sure not to completely mess up when moduling :rolleyes: And my first concern is documentation.

Even Aristoteles knew:
The code is more than the sum of its keywords.
 

MikeHart

Administrator
Joined
Jun 19, 2017
Location
Germany
Are there existing rules for creating good modules?
No there are not.
I mean, I could look how it's done with other modules.
That is how I did it.
How to do a good documentation of your module. Preferably coming with a documentation of .cerberusdoc-file syntax.
At the end, the user of your module will tell you if the documentation is good or not. Examples inside the documentation is something I heard all the time. And shipping your module with some. Make sure your module doesn't create name conflicts. So some kind of prefix is good to use. Study how the module docs are build from the ones that ship with CX. Study the MakeDocs section in the help files.

If you have any more questions, please let us know.
 

PixelPaladin

Active Member
CX Code Contributor
3rd Party Module Dev
Joined
Aug 27, 2017
Location
Germany
I think there were naming conventions for monkey-x so there should exist rules for cerberus.
however at the moment I cannot find anything …

In the standard modules the following naming conventions exist:

variable names:
start with a lowercase letter, are written in camel case
example: fooBar

Functions, Methods, Class:
start with an uppercase letter, written in camel case
example: FooBar

Constants:
all letters uppercase, written in snake case
example: FOO_BAR

private variable names, function names, … start with an underscore
example: _fooBar, _FooBar(), _FOO_BAR, …

(are there more?)

When writing a module that should be used by others you should make use of the keywords 'private', 'public' and 'protected'.
By the way it seems like some keywords like 'protected' or 'friend' are even missing in the documentation. Maybe we should create a topic for stuff that is missing in the docs since an incomplete documentation is a no go.

The documentation for makedocs also seems incomplete so here is a short summary (I'm not sure if this is complete):

module description:
Code:
# Module <modul_name>
<description>
imports:
Code:
# Import <module>
constants:
Code:
# Const <name>:<type>
<description>
fields:
Code:
# Field <name>:<type>
<description>
classes:
Code:
# Class <name> Extends <parent_class> Implements <interfaces>
<description>
interfaces:
Code:
# Interface <interface_name>
<description>
or:
Code:
# Interface <module>.<interface_name>
<description>
methods:
Code:
# Method <methodname>:<datatype>(<parameters>)
<description>
functions:
Code:
# Function <methodname>:<datatype>(<parameters>)
<description>
or:
Code:
# Function <module>.<methodname>:<datatype>(<parameters>)
<description>
class functions:
Code:
# Function <class>.<function_name>:<datatype>(<parameters>)
<description>
or
Code:
# Function <module>.<class>.<function_name>:<datatype>(<parameters>)
<description>

comments:
Code:
'this is a comment
description text (multiple lines of text)
Code:
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed
diam nonumy eirmod tempor invidunt ut labore et dolore
magna aliquyam erat, sed diam voluptua. At vero eos et
accusam et justo duo dolores et ea rebum. Stet clita kasd
gubergren, no sea takimata sanctus est Lorem ipsum dolor
sit amet.
headlines:
Code:
> headline1
>> Headline2
>>> Headline3
highlight words (bold):
Code:
@foo
numeric ordered lists:
Code:
+ first list node
+ second list node
+ thirdlist node
unordered lists:
Code:
* first list node
* second list node
* thirdlist node
tables:
Code:
|First Header |Second Header |Third Header
|cell 1 |cell 2 |cell 3
|cell 4 |cell 5 |cell 6
|cell 7 |cell 8 |cell 9
code blocks:
Code:
<pre>
   <examplecode>
</pre>
links to members (like methods):
Code:
[[<member>]], [[<member>]]
or:
Code:
[[<class>.<member>|<member>]], [[<class>.<member>|<member>]]
inline html:
It is possible to use inline html.
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
Thanks

I must have missed the MakeDocs section.

This and your advice should get me through documenting my modules

:eek: a new post while I'm typing here?

*read*

Thanks, PixelPaladin! That's really helpful. What does protected do?
 

PixelPaladin

Active Member
CX Code Contributor
3rd Party Module Dev
Joined
Aug 27, 2017
Location
Germany
Protected works a bit like private but you can access protected variables when writing a class that extends another class.

Example:
Code:
'a.cxs
Public Class A
    Protected Field x:Int
End

'b.cxs
Import a
Public Class B Extends A
    Method Foo:Void()
        x=3
    End
End
 

Gerry Quinn

Active Member
Joined
Jun 24, 2017
Protected didn't exist for a long time in Monkey, so I got used to using just Public and Private (and Private I use sparingly - Mark was far too free with it IMO, e.g. nodes in Lists. Now I think of it, should we re-evaluate those choices, and make stuff like lists more extensible? It won't break any non-terrible, non-strict code!)
 
Top Bottom