STYLE_GUIDE.md

R3BL code style guide

Table of contents

• Ideals
  • Favor convention over ceremony
  • Favor readability over cleverness
  • Favor readability over brevity
  • Favor readability over verbosity
  • Favor well named intermediate variables over brevity
  • Favor loosely coupled and strongly coherent over tightly coupled
  • Favor shallow imports over deep ones by re-exporting from modules
• Examples
  • Using DSLs where appropriate

Ideals

1. Favor convention over ceremony

2. Favor readability over cleverness

3. Favor readability over brevity

4. Favor readability over verbosity

5. Favor well named intermediate variables over brevity

6. Favor loosely coupled and strongly coherent over tightly coupled

7. Favor shallow imports over deep ones by re-exporting from modules

TK: Take some inspiration from https://kotlinlang.org/docs/coding-conventions.html

Examples

Using DSLs where appropriate

Here's an example of using a DSL to make code more readable, and respecting the following rules from above:

• favor readability over verbosity
• favor well named intermediate variables over brevity

What is a DSL? A DSL is a domain-specific language. Here are two good resources to learn about them:

• https://en.wikipedia.org/wiki/Domain-specific_language
• https://docs.microsoft.com/en-us/visualstudio/modeling/how-to-define-a-domain-specific-language?view=vs-2022

pub fn append_quit_msg_center_bottom(queue: &mut TWCommandQueue, size: Size)  {
  let message: String = "Press Ctrl + q to exit!".into();
    [
      TWCommand::MoveCursorPositionAbs(((size.cols / 2) - message.chars().count() as u16 / 2, size.rows - 1).into()),
      TWCommand::PrintWithAttributes(message, None),
    ].iter().for_each(|cmd| {
      queue.push(cmd.clone());
    });
}

pub fn append_quit_msg_center_bottom(queue: &mut TWCommandQueue, size: Size) {
  let message: String = "Press Ctrl + q to exit!".into();
  let col_center: UnitType = size.cols / 2 - convert_to_base_unit!(message.len()) / 2;
  let row_bottom: UnitType = size.rows - 1;
  tw_command_queue!(
  queue push
    TWCommand::MoveCursorPositionAbs((col_center,row_bottom).into()),
    TWCommand::PrintWithAttributes(message, None)
  );
}