feat(software): improved file organization

2025-02-15 14:28:35 -07:00
parent 5bac5ada19
commit 4a272b2686
4 changed files with 0 additions and 0 deletions
--- a/Software/Commenting
+++ b/Software/Commenting
@ -0,0 +1,178 @@
+
+# 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;
+```