[FEATURE] - Style Guide, Best Practices, etc.

[briandowns]

Is there an existing issue for this?

• [X] I have searched the existing issues

Is your feature request related to a problem?

Most languages have some form of a style guide helping users write idiomatic and stylistically correct code. I was hoping to maybe start the conversation around having such a guide for Dictu.

Describe the solution you'd like

No response

Describe alternatives you've considered

No response

Additional context

No response

[Jason2605]

Yeah it's a good idea, having some sort of conventions on the docs somewhere could be a good start. Later down the road we could potentially start creating a linter that helps enforce these rules as well

[briandowns]

@Jason2605 Happy for any and all feedback on the proposal below. Not married to any of the opionions.

Introduction

These guidelines attempt to provide a framework for code styling and formatting with the end goal of having all Dictu code similar enough for maximal familiarity and readability.

Formatting

Favor 4 spaces over tabs.

Commentary

Dictu supports single and multiline comments in the form of // and /** */ respectively. Declaration comments should use the former.

For example:

// class User provides ...
class User {
    private password;
    
     // User class initializer. Creates a new user value, sets the given name fields,
     // and generates a new password.
    init(var firstName, var lastName) {
        // generate a new password.
        this.password = generatePassword();
    }
}

Module Names

Depending on how a module is imported, either the module name becomes the accessor or the item imported is accessed directly. Modules should have short names and be simple nouns describing the contents. For example: Sockets, HTTP, System.

import System;

Imports

Imports should be grouped together into 3 seconds. The first section is for regular imports from the standard library. The second is for from imports from the standard library. And the third is for local file based imports. The 3 above sections should be seperated by 1 line and listed alphabetically.

import Env;
import HTTP;
import Sockets;

from Argparse import Parser;

from "standard_model/particles.du" import Boson;
from "standard_model/particles.du" import Quark;

Mixed Caps

The naming convention in Dictu is to use mixed caps, Camel Case and Pascal Case, to write multiword names.

Constants

Constants should be defined using snake case. E.g. const CONSTANT_VALUE = 10;

Control Flow

Dictu provides a number of control structures allowing for robust functionality. These strcutures should be formatted as follows:

if () {
    // code
}

while () {
    // code
}

for (...) {
    // code
}

Error Handling

The Result type is preferred for error handling and include values to be unwrapped. 2 common patterns have emerged to be the most common. These are preferred and can be referenced below:

const val = someFunc().match(
    def(result) => result,
    def(error) {
        print(error);
        System.exit(0);        
    }
);

const ret = someFunc();
if (not ret.success()) {
    // do something with the error
    ret.unwrapError();
}