• Dear Cerberus X User!

    As we prepare to transition the forum ownership from Mike to Phil (TripleHead GmbH), we need your explicit consent to transfer your user data in accordance with our amended Terms and Rules in order to be compliant with data protection laws.

    Important: If you accept the amended Terms and Rules, you agree to the transfer of your user data to the future forum owner!

    Please read the new Terms and Rules below, check the box to agree, and click "Accept" to continue enjoying your Cerberus X Forum experience. The deadline for consent is April 5, 2024.

    Do not accept the amended Terms and Rules if you do not wish your personal data to be transferred to the future forum owner!

    Accepting ensures:

    - Continued access to your account with a short break for the actual transfer.

    - Retention of your data under the same terms.

    Without consent:

    - You don't have further access to your forum user account.

    - Your account and personal data will be deleted after April 5, 2024.

    - Public posts remain, but usernames indicating real identity will be anonymized. If you disagree with a fictitious name you have the option to contact us so we can find a name that is acceptable to you.

    We hope to keep you in our community and see you on the forum soon!

    All the best

    Your Cerberus X Team

Are there existing rules for creating good modules?

Holzchopf

Well-known member
3rd Party Module Dev
Tutorial Author
Joined
Jul 31, 2017
Messages
500
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.
 
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.
 
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.
 
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?
 
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
 
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!)
 
Back
Top Bottom