Baja-Charter/Software/Commenting Pratices.md

# When does code need comments

## Needs Comments
This example needs comments
```rust
fn main () {
    let length1 = 8;
    let width1 = 4;

    println!("The area of a rectangle is {} square units.",
    area(length1, width1)
}

fn area (length: i32, width: i32) -> i32 {
    length * width
}
```

Not really great nothing related needs specifically named variables that losely relate to one another.

Variables are ambiguous to their relationship, for example is `length1` related to `rectange1` or some other rectangle (who knows)


## Needs comments for a differnent reason, not well defined relationship
Here is a bit better but still needs comments to define the relationship and what is going on
```rust
fn main () {
    let rectangle1 = (8, 4);
    println!("The area of a rectangle is {} square units.",
    area(rectangle1)
    );
}

fn area (dimensions: (i32, i32)) -> i32 {
    dimensions.0 * dimensions.1
}
```
Now what does the first and second index of the tuple mean?

It could be width then length this is still ambugious

## Very Little Comments Required
This is very clear from a first read but it could use some comments
```rust
struct Rectangle {
    length: u32,
    width: u32,
}
fn main () {
    let rect1 = Rectangle {
        length: 8,
        width: 4,
    };
    println!("The area of a rectangle is {} square units.",
    area(&rect1)
    );
}

fn area (rect: &Rectangle) -> u32 {
    rect.length * rect.width
}
```

Could be better due to the way that shapes all have unique area formulas

In this case it should be a method that implements a `trait` (a common shared method, also known as a interface) so that its relationship is very well defined

## The Worst Code I Have Written

This is when things needs to be refactored because comments cannot save it

This code was written by Brock
```javascript
			<div id="Sponsor">
				<h2 className="SponsorsTitle">Current Sponsors</h2>
				{/* shows the current sponsors only after the data has been recieved */}
				{currentSponsorsDict === undefined ? (
					<p>Loading...</p>
				) : (
					<>
						{/* gets the outmost name of the Object Name of tier*/}
						{Object.keys(currentSponsorsDict).map((sponsorsTier) => {
							return (
								<div className="Sponsors">
									<h3>{sponsorsTier}</h3>
									{/* gets key form list of tier */}
									{Object.keys(currentSponsorsDict[sponsorsTier]).map(
										(sponsorsKey) => {
											return (
												<>
													{/* gets name out of object and gets data of that sponsor preped */}
													{Object.keys(
														currentSponsorsDict[sponsorsTier][sponsorsKey]
													).map((sponsorName) => {
														let sponsorData =
															currentSponsorsDict[sponsorsTier][sponsorsKey][
																sponsorName
															];
														return (
															<a
																href={sponsorData.Url}
																target="_blank"
																rel="noreferrer">
																<div>
																	<h4>{sponsorName}</h4>
																	<img
																		src={sponsorData.LogoUrl}
																		alt={sponsorName + "'s Logo"}
																	/>
																</div>
																{(sponsorsTier !== "Silver Tier" ||
																	sponsorsTier !== "Bronze Tier") && (
																	<div>
																		<p>{sponsorData.DescriptionAboutSponsor}</p>
																	</div>
																)}
															</a>
														);
													})}
												</>
											);
										}
									)}
								</div>
							);
						})}
					</>
				)}
			</div>
			<div id="Sponsor">
				<h2
					className="SponsorsTitle"
					id="SponsorEnd">
					Past Sponsors
				</h2>
				{/* shows past sponsors only when recieved, do not duplicate the sponsors from current ones */}
				{pastSponsorsDict === undefined ? (
					<p>Loading...</p>
				) : (
					<>
						{/* gets keys o objects in list */}
						{Object.keys(pastSponsorsDict).map((pastSponsorKey) => {
							return (
								<div className="Sponsors">
									{/* gets name of sponsor then uses it to get data of past sponsor */}
									{Object.keys(pastSponsorsDict[pastSponsorKey]).map(
										(pastSponsorName) => {
											let pastSponsors =
												pastSponsorsDict[pastSponsorKey][pastSponsorName];
											return (
												<a
													href={pastSponsors.Url}
													target="_blank"
													rel="noreferrer">
													<div>
														<h4>{pastSponsorName}</h4>
														<img
															src={pastSponsors.LogoUrl}
															alt={pastSponsorName + "'s Logo"}
														/>
													</div>
												</a>
											);
										}
									)}
								</div>
							);
						})}
					</>
				)}
			</div>
		</div>
	);
};

export default OurSponsors;
```