Madara community call #6

[AbdelStark]

Madara Project - 6th Community Call Announcement

Hello, Madara community members! 🎉 We're excited to invite you to our 6th Community Call, where we'll discuss the latest project updates, share insights, and gather valuable feedback from all of you.

Agenda

• Backlog Review and Task Updates from Contributors
• Plan for Cairo 1.0 support (@tdelabro)
• Coding practices (@abdelhamidbakhta) -
• Benchmark infrastructure (@ClementWalter)
• Deep dive on starknet_getEvents (@greged93 )
• Deep dive on starknet_addInvokeTransaction (@drspacemn)

Information

• When: Fri, 2 Jun 2023 at 3:30 PM CEST

Paris, France Fri, 2 Jun 2023 at 15:30 CEST
New York, USA Fri, 2 Jun 2023 at 09:30 EDT
UTC, Time Zone Fri, 2 Jun 2023 at 13:30
Sydney, Australia Fri, 2 Jun 2023 at 23:30 AEST

"Wherever There Is Light — There Are Always Shadows."

[AbdelStark]

Madara: Coding Principles and Best Practices Guide

Table of Contents

• Madara: Coding Principles and Best Practices Guide
  • Table of Contents
  • 1. Introduction
  • 2. Clean Code
  • 3. Principles
    • 3.1 KISS: Keep It Simple, Stupid
    • 3.2 YAGNI: You Aren't Gonna Need It
    • 3.3 DRY: Don't Repeat Yourself
    • 3.4 SRP: Single Responsibility Principle
  • 4. Conclusion

1. Introduction

This document outlines the principles and practices we strive to uphold in the development of the Madara project. We aim to create a codebase that is clean, maintainable, and efficient. To achieve this, we draw inspiration from principles laid out in various reference books, most notably Clean Code: A Handbook of Agile Software Craftsmanship.

2. Clean Code

A core philosophy of our project is to create clean, readable, and maintainable code. Clean code allows developers to understand the code better, reduce bugs, and ease the maintenance process.

In the spirit of Clean Code, we strive to:

• Write meaningful names
• Write small functions doing one thing
• Minimize the number of function arguments
• Avoid side effects
• Write DRY code
• Write unit tests
• Write meaningful comments

An example of clean code in Rust could be:

pub struct Circle {
    radius: f64,
}

impl Circle {
    pub fn new(radius: f64) -> Circle {
        Circle { radius }
    }

    pub fn area(&self) -> f64 {
        std::f64::consts::PI * self.radius * self.radius
    }
}

This simple Circle struct and its implementation is clean: it's straightforward, self-describing, and only has the necessary functionality.

3. Principles

3.1 KISS: Keep It Simple, Stupid

The KISS principle states that simplicity should be a key goal in design and unnecessary complexity should be avoided. This will make your code more readable and maintainable.

Here's an example of adhering to the KISS principle:

// Complex way
fn calculate_sum(numbers: &[i32]) -> i32 {
    let mut sum = 0;
    for i in 0..numbers.len() {
        sum += numbers[i];
    }
    sum
}

// KISS way
fn calculate_sum(numbers: &[i32]) -> i32 {
    numbers.iter().sum()
}

3.2 YAGNI: You Aren't Gonna Need It

The YAGNI principle emphasizes not adding functionality until it is necessary. This reduces complexity and increases code maintainability.

struct User {
    id: i32,
    name: String,
    // age: i32, // YAGNI, don't add it until it's necessary
}

impl User {
    fn new(id: i32, name: String) -> User {
        User { id, name }
    }
}

3.3 DRY: Don't Repeat Yourself

The DRY principle is aimed at reducing repetition. It helps to lower the chance of bugs and makes the code more maintainable.

// Violates DRY
fn add_ten(num: i32) -> i32 {
    num + 10
}

fn add_twenty(num: i32) -> i32 {
    num + 20
}

// Follows DRY
fn add_n(num: i32, n: i32) -> i32 {
    num + n
}

In this case, instead of having separate functions to add ten or twenty to a number, we can have a general function to add any integer to another.

3.4 SRP: Single Responsibility Principle

SRP suggests a component of software (a module, a class, or a function) should have one, and only one, reason to change.

Let's look at a struct that violates the SRP:

pub struct Report {
    title: String,
    data: Vec<String>,
}

impl Report {
    pub fn new(title: String, data: Vec<String>) -> Report {
        Report { title, data }
    }

    pub fn print(&self) {
        println!("Title: {}", self.title);
        for line in &self.data {
            println!("{}", line);
        }
    }

    pub fn format(&mut self) {
        self.data = self.data.iter().map(|line| format!("{}\n", line)).collect();
    }
}

Here, the Report struct is responsible for data handling (new, format) and for output (print). This violates the Single Responsibility Principle.

A better approach is to separate these responsibilities into different structs:

pub struct Report {
    title: String,
    data: Vec<String>,
}

impl Report {
    pub fn new(title: String, data: Vec<String>) -> Report {
        Report { title, data }
    }

    pub fn format(&mut self) {
        self.data = self.data.iter().map(|line| format!("{}\n", line)).collect();
    }
}

pub struct ReportPrinter {
    report: Report,
}

impl ReportPrinter {
    pub fn new(report: Report) -> ReportPrinter {
        ReportPrinter { report }
    }

    pub fn print(&self) {
        println!("Title: {}", self.report.title);
        for line in &self.report.data {
            println!("{}", line);
        }
    }
}

Now, Report is responsible for data handling, and ReportPrinter is responsible for output. Each struct now has a single responsibility.

4. Conclusion

This document laid out the core coding principles we strive to uphold in the Madara project. Remember, these are principles, not strict rules. They are meant to guide us towards producing a clean, maintainable, and efficient codebase. The purpose is not to create perfect code, but to aim for better code every day. Let's write some clean and beautiful Rust code together!

[AbdelStark]

Reveal slides

<div class="slides">
    <section data-markdown>
        <textarea data-template>
            # Madara: Coding Principles and Best Practices Guide
        </textarea>
    </section>
    <section data-markdown>
        <textarea data-template>
            ## 1. Introduction

            - We strive for clean, maintainable, and efficient code.
            - We draw inspiration from Clean Code: A Handbook of Agile Software Craftsmanship.
        </textarea>
    </section>
    <section data-markdown>
        <textarea data-template>
            ## 2. Clean Code

            - Clean code allows developers to understand the code better, reduce bugs, and ease the maintenance process.
            - We strive to write meaningful names, small functions, DRY code, unit tests, and meaningful comments.
        </textarea>
    </section>
    <section>
        <section data-markdown>
            <textarea data-template>
                ### 2.1 Clean Code Example
              
                ```rust
                pub struct Circle {
                    radius: f64,
                }
                impl Circle {
                    pub fn new(radius: f64) -> Circle {
                        Circle { radius }
                    }
                    pub fn area(&self) -> f64 {
                        std::f64::consts::PI * self.radius * self.radius
                    }
                }
                ```
            </textarea>
        </section>
        <section data-markdown>
            <textarea data-template>
                ### 3.1 KISS: Keep It Simple, Stupid
              
                - Keep your design simple and avoid unnecessary complexity.
              
                ```rust
                // KISS way
                fn calculate_sum(numbers: &[i32]) -> i32 {
                    numbers.iter().sum()
                }
                ```
            </textarea>
        </section>
        <section data-markdown>
            <textarea data-template>
                ### 3.2 YAGNI: You Aren't Gonna Need It
              
                - Don't add functionality until it is necessary.
              
                ```rust
                struct User {
                    id: i32,
                    name: String,
                    // age: i32, // YAGNI, don't add it until it's necessary
                }
                ```
            </textarea>
        </section>
        <section data-markdown>
            <textarea data-template>
                ### 3.3 DRY: Don't Repeat Yourself
              
                - Reducing repetition helps to lower the chance of bugs and makes the code more maintainable.
              
                ```rust
                // Follows DRY
                fn add_n(num: i32, n: i32) -> i32 {
                    num + n
                }
                ```
            </textarea>
        </section>
        <section data-markdown>
            <textarea data-template>
                ### 3.4 SRP: Single Responsibility Principle
              
                - A component of software should have one, and only one, reason to change.
              
                ```rust
                // SRP
                pub struct Report {
                    title: String,
                    data: Vec<String>,
                }
                pub struct ReportPrinter {
                    report: Report,
                }
                ```
            </textarea>
        </section>
    </section>
    <section data-markdown>
        <textarea data-template>
            ## 4. Conclusion

            - These are principles, not strict rules.
            - They guide us towards a clean, maintainable, and efficient codebase.
            - Let's write some clean and beautiful Rust code together!
        </textarea>
    </section>
</div>