| Namn och förklaring | Reflektion och regler från Clean code |
|---|---|
| generateRandomNumber : Metodnamn i NumberGenerator klassen. Genererar ett slumpmässigt nummer. | Don't be cute : Namnet är klart & tydligt och berättar vad metoden gör, varken mer eller mindre. Pick one word per concept : Ordet "generate" används i hela modulen i metoder som genererar olika typer av data. |
| StringGenerator : Klassnamn för klass som kan generera strängar. | Use Intention-Revealing Names : Namnet är tydligt och berättar dens syfte. Man förstår att det är en klass som genererar strängar. Class Names : Namnet är ett substantiv vilket är bra, klassnamn bör inte vara verb. |
| generateRandomRGBColor : Metodnamn i ColorGenerator klassen. Genererar ett RGB värde. | Use Searchable Names : Ett unikt och ganska långt namn som gör det lätt att söka upp. Avoid Disinformation : Möjligt att namnet inte är helt tydligt med vad som faktiskt genereras. En färg? Hur då? Vad får man ut? En del programmerare kanske förstår direkt att det är en sträng men inte säkert alla gör det. Ett bättre men längre namn kanske är: generateRandomRGBColorString ? Eller: generateRGBColorString |
| generateRandomNumbersArray : Metodnamn i klassen ArrayGenerator. Genererar en array bestående av slumpmässiga nummer. | Make Meaningful Distinctions : Metodnamnet är långt och beskrivande men kanske lite väl långt. Hade verkligen ordet Array behövt vara med? Eftersom "Numbers" tyder på att det är flera nummer som generas och då alltså en array. Avoid Mental mapping : Namnet är som sagt beskrivande och ordet "Numbers" ger användaren av metoden en påminnelse att arrayen bara innehåller nummer. Användaren behöver inte komma ihåg den här infon i minnet utan det står tydligt vad metoden genererar. |
| generateRandomDate : Metodnamn i klassen DateGenerator. Genererar ett slumpmässigt datum. | Method Names : Metodnamn bör vara verb eller verbfraser. Use Pronouncable Names : Kanske inte specifikt bara för den här metoden utan jag har försökt applicera den här regeln på alla metoder och klasser. |
Namngivning av funktioner/klasser/variabler är något som jag verkligen försökt vara noggrann med ända sedan jag började studierna förra året. Ibland kan det dock kanske ta lite väl lång tid och bli lite väl långa eller övertydliga namn så det gäller att hitta en balans där. I denna laborationen kan det kanske blivit lite väl långa namn och jag kunde säkert kortat ner dem samtidigt som jag behållt tydligheten. Jag tänker att ju mer jag programmerar kommer det gå snabbare att hitta bra och tydliga namn för min kod då man har byggt upp sin kunskap- och ordbank ytterligare. Jag håller med om allt som står i boken, jag har alltid försökt namnge allting så beskrivande och tydligt det bara går. En brist som jag möjligen har haft i mina tidigare projekt (lite osäker, kommer inte ihåg all kod jag skrivit) är regeln Pick One Word Per Concept. Jag kan nog ha använt mig av lite olika termer för i stort sett samma sak istället för att hålla mig till samma term/ord. Jag tror det kan handla om en osäkerhet som ny programmerare att inte veta vilken term som passar bäst in på det man vill åstadkomma och då kan det bli att man väljer att "täcka upp" genom att använda olika termer för samma sak. En sak jag gillar med kapitel 2 och namngivning överlag är att det gör kod så mycket enklare att förstå för mig som ny programmerare. Jag kan fortfarande tycka det är svårt att läsa andras kod men har någon lagt lite extra tid på namngivning så hjälper det väldigt mycket och jag förstår koden snabbare.
| Namn och förklaring | Antal rader (ej ws) | Reflektion och regler från Clean code |
|---|---|---|
| generateRandomStringsArray(lengthOfArray, minStringLength, maxStringLength) : Genererar en array av slumpmässiga strängar som har en slumpmässig längd beroende på användarens input. | 12 | Small! : Metoden är, trots det är en av mina längsta, relativt liten och lätt att se hela metoden utan att behöva scrolla. Function Arguments : Metoden har tre argument (triadic) vilket inte är att föredra och borde undvikas. Jag hade kunnat skicka in ett argument som ett objekt istället. Man kan dock välja att inte skicka in några argument, då kommer det generaras en array utifrån några standarvärden(default values) som jag har satt. Så argumenten är mest till för att göra metoden och arrayen mer anpassningsbar för användaren. |
| generateRandomNumbersArray(lengthOfArray, minValueInArray, maxValueInArray) : Genererar en array av slumpmässiga nummer inom ett visst intervall som användaren kan bestämma. | 11 | Use Descriptive Names : Ett långt och tydligt namn som berättar exakt vad metoden gör (Känns lite som kapitel 2 fokus men regeln finns med i kapitel 3 i boken.). Do One Thing : Genererar en array med nummer och inget annat. Delegerar valideringen av argumenten vidare till annan metod och har huvudfokuset på att generera en array. (Om jag tolkat det rätt så utför inte den här metoden någon validering utan kallar på en annan metod som utför det. Innebär det att denna metoden gör fler än en sak? Kanske, men jag väljer att inte tolka det så för då känns det som det blir väldigt svårt att skriva bra funktioner) Don't repeat yourself : I både denna metoden och den precis ovanför i tabellen skulle jag kunna bryta ut en viss del av koden till en egen funktion då jag upprepar mig och skriver samma kod i båda metoderna (När jag tar fram randomNumber och randomLength EDIT: Jag har nu åtgärdat detta). I denna metoden gäller också samma regler och reflektioner som jag skrev precis ovanför i tabellen. |
| #validateStringArray(minStringLength, maxStringLength) : Validerar användares input till metoden generateRandomStringsArray() | 11 | Do one thing: : Här utförs enbart validering och inget annat. Use Descriptive Names : Visst är namnet långt och man får en viss bild av vad den gör men i själva verket kanske den borde heta "validateStringArrayArguments" så man verkligen förstår att det är användarnas input som valideras? Function argument : Metoden har två argument och är en dyadic funktion. Vilket är bättre och mer acceptabelt än en triadic som jag skrivit om här ovan, men ändå inte det mest optimala. |
| generateRandomString(customLength) : Genererar en slumpmässig sträng, användaren har möjlighet att bestämma längd. | 8 | Function arguments : Den här metoden har bara ett argument (monadic) vilket anses vara det näst bästa alternativet enligt Clean Code. Blocks and Indenting : Metoden har en for loop som bara innehåller en rad med kod vilket Clean Code förespråkar. Dock menar de att den raden förmodligen bör vara ett metodanrop. Jag skulle kunna bryta ut min kod i for loopen till en egen metod och anropa den för att få koden att bli ännu tydligare. |
| generateRandomHexColor() : Genererar en slumpmässig hexfärgkod. | 9 | Function Arguments : Det ideala antalet arguement enligt Clean Code, noll! (niladic) Do One Thing & Small! : Metoden gör enbart en sak, den kallar inte ens på andra metoder. Den är liten och enkel för läsare av koden att förstå. |
Jag försökte att variera reglerna i min tabell här ovan men jag skulle säga att Small! och Do One Thing kan appliceras på alla. Det var iallafall det som var mitt mål när jag skrev dem. Jag hade ytterligare en generateRandomEvenNumbersArray() metod men valde att exkludera den då den är völdigt lik de andra metoderna och samma regler som jag tagit upp gäller för den metoden också. Jag skulle säga att jag håller med om alla reglerna som kapitel 3 tar upp även om jag nu så här i efterhand märkt att jag inte följt alla i mina tidigare projekt under mina studier. Jag har tidigare varit dålig på att följa Do One Thing regeln och något jag måste börja tänka mer på. Tidigare har mina tankar nästan varit att slänga in så mycket som bara går i funktioner för att på så sätt vara "effektiv" (Inte riktigt så extremt kanske men jag har inte haft Do One Thing fokuset iallafall). Samma sak med antal argument man använder sig av, ju fler desto större är risken för komplikationer och fel. Tidigare har jag bara slängt in argument utan att egentligen tänka på det här. Ett beteende som jag får försöka jobba bort, det blev extra påtagligt när jag skrev denna modulen att jag gärna ville använda mig av många argument och jag fick en liten ögonöppnare. Namngivning av mina funktioner och argument har jag hela tiden försökt tänka extra noga på, ibland blir de förmodligen lite väl övertydliga och långa, men som jag förstår det från boken så är tydlighet verkligen A och O när man skriver sin kod. För att uppnå den här tydligheten kan det vara bra att använda sig av Don't repeat Yourself regeln för att inte "kluttra" ned sin kod onödigt mycket. Detta var faktiskt en av de första sakerna vi fick lära oss förra året och något jag försöker tänka på så ofta jag kan när jag skriver min kod.
Jag har redan tagit upp lite egna reflektioner här ovan där jag pratar om mitt kodskrivande, mina brister och vad jag försöker tänka lite extra på. I denna reflektionen blir det därför kanske lite mer generella tankar kring ämnet. Efter att ha läst kapitel 2 och 3 i Clean Code så är min första tanke, och det jag tar med mig, att tydlig och beskrivande kod är något de prioriterar väldigt högt. Jag är beredd att hålla med, åtminstone för mig som relativt ny programmerare är det en mardröm att läsa kod som inte följer till exempel Use Descriptive Names och Use Intention-Revealing Names reglerna. Om vi fortsätter på tydlighets spåret uppskatar jag även att de vill hålla funktionerna korta/små med regler som Small! och Do One Thing. Det var ingenting jag hade kanske förväntat mig när jag började programmera utan jag tänkte att ju större funktion desto ”bättre” och mer komplexa problem går att lösa så. När man sen själv börjar koda så inser man vikten av att tidigt lära sig om hur man skriver kod på ett bra sätt, dels för att själv förstå, dels, som vi i den här kursen lär oss, för att andra ska förstå. Ofta när man kollat upp kodexempel på nätet så försöker en del att göra det till en grej att skriva så ”smart” kod som möjligt med konstiga variabelnamn och komplexa nästlade uttryck (if/for/while osv.). Då känner man sig mest dum när man kollar på koden och inte förstår. Nu efter att ha påbörjat denna kurs får jag en liten annan syn på det hela och förstår att det är inte nödvändigtvis så det ska vara. Bra kod SKA vara tydlig och beskrivande, det ska vara lätt för andra att sätta sig in i. Visst kan det vara skoj att hitta oortodoxa lösningar till småproblem men i ett riktigt jobbscenario är det verkligen bra kod om man själv är den enda som förstår vad den gör? Så jag kommer fortsätta lägga ner den lilla extra tiden det tar för att namnge mina variabler, klasser och funktioner. Det hjälper ju faktiskt inte bara mig utan också andra programmerare. Jag kommer sträva efter att hålla mina funktioner så korta och enkla som möjligt. Det tycker jag känns som den riktigt roliga utmaningen: ”Hur kan jag göra den här funktionen så liten som möjligt samtidigt som den bara gör en sak som ALLA förstår?”. Inte komma på någon komplex lösning med nästlade uttryck man inte hänger med i förrän man läst koden x antal gånger. Jag skulle säga att jag själv har varit bättre på att följa reglerna från kapitel 2 så här i början av min programmeringsresa men allt eftersom man nu börjar bli lite varm i kläderna så kommer jag definitivt ha kapitel 3:s regler i bakhuvudet när jag skriver min kod.