Baja-Charter/Software/Commenting Pratices.md

When does code need comments

Needs Comments

This example needs comments

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

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

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

			<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;