[Draft] Let Statements

[x0rw]

Can someone review, and show me how do i properly link each point to FLS?
Note: This is a preliminary draft and has not yet been formatted in reStructuredText (.rst) format

Ferrocene spec - let statements

1.1 Always Initialize Variables Before Use

bad example:

let x: i32;
x = 42;
println!("x is {}", x);

good example:

let x: i32 = 42;
println!("x is {}", x);

1.2 Prefer Immutable Bindings

Rationale:

• Prevent accidental modifications
• Reducing the risk of unintended side effects
• Immutable bindings reduce the number of possible states your system can be in, which is a significant benefit when ensuring the reliability of safety-critical code

let x = 10;

(couldn't come up with an example)

1.3 Use Explicit Types for Critical Values

Rationale

• Explicit types prevent errors that may arise from implicit type inference
• Ensures that the code behaves consistently on different platforms(!!!)

bad example:

fn div_unsafe(a: i32, b: i32) -> f64 {
    let ratio = a / b; // ratio is infered as i32
    ratio as f64  // The conversion happens after integer division
}

good example:

fn div_safe(a: i32, b: i32) -> f64 {
    let ratio: f64 = (a as f64) / (b as f64); //Explicit Conversion to remove any ambiguity that may arise
    ratio
}

1.4 Avoid Shadowing

Rationale

• Using distinct names for different variables avoids ambiguity and improves code readability.
• Ensure Safe let Bindings in Unsafe Blocks
• Reduces the risk of logical errors

bad example:

fn process_sensor() -> f64 {
    let value = read();        // Original reading
    let value = calibrate(value); // Shadowed: now holds calibrated value
    let value = filter(value);    // Shadowed again: now holds filtered value
    value                             
}

good example:

fn process_sensor() -> f64 {
    let value = read();      
    let calibrated_value = calibrate(value); 
    let filtered_value = filter(value);    
    filtered_value                             
}

Another point: How do I ensure that the examples do not violate other guidelines?
Also, should the use of mut require documentation or a comment?

[x0rw]

in 1.3 Use Explicit Types for Critical Values should i mention using explicitly-sized types (e.g.,i32, u32, ...) instead of platform-dependent types (e.g., usize, isize, ...) or leave them to be referenced later?

[rcseacord]

Put the noncompliant example first followed by the compliant solution

[x0rw]

Put the noncompliant example first followed by the compliant solution

Done, let me know if there is something else

[PLeVasseur]

Hi @x0rw -- thanks for bringing this topic!

show me how do i properly link each point to FLS?

I found the easiest way was to right click on the section number and then click Inspect:

We can then see it in the page source:

[x0rw]

Thanks, that's easier.
Another problem is aligning a guideline with the right FLS, for example, the guideline below, it's hard to find a specific FLS for that aligns with it

1.3 Use Explicit Types for Critical Values

[PLeVasseur]

Hey there @x0rw -- I'd say to use your best judgement. I'd be surprised if there is no paragraph ID, but it may be possible.

Could you explain a little more about what you're finding hard about it?

[Veykril]

Re:Content: A trick that might worth integrating to reduce the mutable scope of locals if mutability is required temporarily:

let thing = {
     let mut thing = ...;
     do_the_mutable(&mut thing);
     thing
};
// now thing is immutable from here on

[x0rw]

Re:Content: A trick that might worth integrating to reduce the mutable scope of locals if mutability is required temporarily:

let thing = {
     let mut thing = ...;
     do_the_mutable(&mut thing);
     thing
};
// now thing is immutable from here on

Hey Veykril, I wonder if this should be added as a whole subsection or just as a sidenote or alternative.