SPRINT FOUR REFLECTIONS

My Reflections - Sprint Four

Learning Competencies

By the end of this primer, you should be familiar with and able to explain:

• What code readability is ☑️
• Why it's an important skill to have as a developer ☑️
• What code readability habits you can start building on today ☑️

My Reflections - Sprint Four

Good developers write code fast and with a low bug-rate. Great developers read existing code, reuse and improve them, generating higher quality code with no duplication and reduced bug-rate for both new and existing code. We should write readable code; written for humans and not just for machines. And we should read code and improve, rather than rewriting.

What makes code more readable for you?

From http://blog.ashodnakashian.com/2011/03/code-readability/

Code Readability

Code Readability is about practising the following habits when you are working on code:

• Indentation/formatting your code to best practice standards.
• Consistency in how you name things and how you format your code.
• Naming things well (things like functions and variables) so you can tell what they do or are.
• Break things into small segments (many small functions compared to one big function).
• D.R.Y (Don't Repeat Yourself).
• Commenting a complicated section so people have some idea before reading your code.
• Not commenting everything or obvious things.
• Refactoring.
• Clean code.

To make things more concrete, here are some of my top readability points:

1. Consistency.I can read code with virtually any convention, no problem. I’ve grown to learn to adapt. If I think I need to read code, then I better accept that I may very well read code not written in my favorite style. One thing that is nearly impossible to adapt to, however, is when the code looks like it’s written by a 5 year old who just switched from Qwerty keyboard to Dvorak.Whatever convention you choose or get forced to use, just stick to it. Make sure it’s what you use everywhere in that project.
2. Consistency.There is no way to stress how important this is. People experiment with braces-on-next-line and braces-on-same-line and forget that their experiments end up in the source repository for the frustration of everyone else on the team. Seriously, experimentation is fine. Finding your preferred style is perfectly Ok. Just don’t commit them. Not in the Trunk at least.
3. Space out the code.Readable code is like readable text. As much as everyone hates reading text-walls, so do developers who have to read sandwiched code. Put empty lines between all scopes. An end-brace is a great place to add that extra line to make it easier to read and find the start of the next scope. Need to comment? Great. Just avoid newspaper-style coding, where the code is turned into a two-column format, code on the left, comments on the right. There are very few cases that one needs to do that. Comments go above the code block or statement, not next to it. Comments are also more readable if they are preceded by a blank line. There is no shortage of disk space. Break long functions, break mega classes and even break long files. Make your functions reasonable in size. Use cyclomatic complexity metrics to know when your code is too complex and hence hard to read and understand. Refactor.
4. Stop banner-commenting.If you need to add 5 lines of boxed comments within functions, then it’s a good indication you need to start a new function. The banner can go above the new function. As much as I’d rather not have it there either, it’s much better than having a 1000+ lines in a single function with half a dozen banners. After all, if you need to signal the start of a new logical block, functions do that better. Same goes to breaking long functions, classes and files. (Unlike what the image above may imply, that image is just an image of some code, I do not endorse the style it adopts.)
5. Don’t use magic numbers.Constants are a great tool to give names to what otherwise is a seemingly magic number that makes the code work. Default values, container limits, timeouts and user-messages are just some examples of good candidates for constants. Just avoid converting every integer into a constant. That’s not the purpose of constants and it reduces code readability.
6. Choose identifier names wisely.There has been no shortage of literature on naming conventions and the perils of choosing names that lack significant differences. Yet, some still insist on using very ambiguous names and reuse them across logical boundaries. The identifiers not only need to be meaningful and unambiguous, but they also need to be consistent across functions, classes, modules and even the complete project. At least an effort to make them consistent should be made. If you need to use acronyms, then make sure you use the same case convention. Have database or network connections, use the same identifier names everywhere. It’s much, much more readable to see an identifier and immediately know what the type is. Incidentally, this was the original purpose of Hungarian notation (original paper.aspx)). Same goes to function names. ‘Get’ can be used for read-only functions that have no side-effects. Avoid using verbs and nouns in an identifier then implement logic that contradicts the natural meaning of those words. It’s downright inhumane. If a functions claims to get some value, then that function should never modify any other value (with the possible exception of updating caches, if any, which should only boost performance without affecting correctness.) Prefer using proper names in identifiers. Meaningful names, nouns and verbs can be a great help, use them to their limit.
7. Don’t chain declarations.Chaining variable declarations is a very common practice in C. This is partially due to the fact that Ansi C didn’t allow declaring variables after any executable statement. Developers had to declare everything up-front and at the top of their functions. This meant that all the variables of a given type were declared in a chain of commas. Declare variables in the innermost scope possible and as close to the usage statement as possible. Avoid recycling variables, unless it’s for the very same purpose. Never re-purpose variables, instead, declare new ones.A similar practice is sometimes used to chain calls where a single function call which takes one or more arguments is called by first calling other functions and passing their return values as arguments to the first call. These two types of chaining make readability a painful process. Some people chain 3 or 4 function calls within one another, thinking it’s more compact and therefore better, somehow. It’s not. Not when someone needs to scan the code for side-effects and to find a hard bug. A possible exception to this is chaining calls one after another. Some classes are designed to chain calls such that each call returns a reference to the original instance to call other members. This is often done on string and I/O classes. This type of chaining, if not excessively used and too long, can be helpful and improve readability.
8. Limit line and file lengths.Scrolling horizontally is a huge pain. No one can be reasonably expected to read anything while scrolling left and right for each line. But some people have larger screens than others. Yet some have weaker eye-sight, so use larger fonts. I’ve seen code apparently aligned to 120 characters per line, with occasional 150+ characters per line, back when 17″ screens were the norm. Some don’t even care or keep track of line length. This is very unfortunate as it makes other people’s lives very hard, especially those with smaller screens, lower resolutions and large fonts (read: bad eye-sight.) Code can’t be word-wrapped like article text (without the help of advanced editors.)A good starting point is the legacy standard of 80 characters-per-line (cpl). If we can stick to that, great. We should make an effort to minimize the line-length and 80 characters is not too narrow to make things garbled. For teams who can all work with 100 or 120 cpl, the extra line width can give quite a bit flexibility and improve readability. But again be careful because too long a line and readability suffers yet again. Think how newspapers and magazines have narrow columns and how readable they are. Our wide screens with large footprints are like newspapers and moving our heads to read across the line, as opposed to moving just our eyes, is an extra physical strain and certainly a speed bump that we can do without.
9. Make scopes explicit.Languages often have implicit scopes. The first statement after a conditional or a loop in C-style languages implicitly fall under the conditional or loop, but not consecutive statements. It’s much harder to parse the end of statements using one’s eyeballs to figure out which statement belongs to the implicit scope. Making these cases explicit makes it much easier to see them without much effort. Adding braces and an empty line after the closing brace, even around single-statement scopes does improve readability quite a bit.
10. Comment.Code is very well understood by machines, even when obsecure and mangled. Humans on the other hand need to understand purpose and reason, beyond seeing what a piece of code would do. Without understanding the reasons behind particular constructs, operations and values, no developer can maintain the code in any sensible way. Comments are a great tool to communicate the less obvious aspects of the code. Explain the business needs, implicit assumptions, workarounds, special-requests and the temporary solutions. Talk to your fellow developers through comments. But, as every rule comes with exceptions, avoid over-commenting at all costs. Resist the temptation to declare that an error is about to occure right before throwing an exception. The throw statement is self-commenting. Don’t repeat yourself. Rather, explain why the case is considered unrecoverable at that point, if it’s not obvious. Prefer to write code that speaks for itself. Self-descriptive code is the most readable code.

As a corollary, some code should be made hard to read. You read that right. Code that depends on hacks, bad practices or temporary solutions should be made harder to read. Perhaps my best example is casting. It’s not rare that we need to cast instances of objects to specific types, and while this is a standard practice, it isn’t exactly highly recommended either. Making the casting a little less readable is a good way to force the reader to squint and make sure it’s not a bogus cast. This isn’t unlike italic text which makes reading the text harder and therefore makes it stand out. In the same vein, temporary solutions and hacks should be made to stand out. Adding TODO and FIXME markers are a good start. BUGBUG is another marker for known issues or limitations. Actually, if there is any place for that banner-comment, this would be it. Make known issues stand out like a sore thumb.

As with most things, the above is mostly a guideline, rules of thumb if you will. They are not set in stone and they aren’t complete by any stretch of imagination. There are many obviously important cases left out. Languages, ecosystems, frameworks and libraries come with their own nuances. What’s clear in one language might be very ambiguous in another, and therefore frowned upon. The important thing is to write with the reader in mind, to avoid confusing styles and especially to be mindful of the context and when an explanatory comment is due, and when refactoring is a better choice.

Do you prefer tabs or spaces when indenting?

• I re-structured some html in my index.html file by creating multiple levels of indenting. Admittedly, it is easier to read now. For example

    

  
        

            
Technical Blog
            


            

            

                

                    GIT
                    
                
                

                    CSS

                    
                
                

                    JAVASCRIPT FUNDAMENTALS
                    
                
                

                    PROBLEM SOLVING
                    
                
                

                    JAVASCRIPT PROJECT
                    
                
            
        

    

I totally did not mean to embed that code in here like this. But I like this. Will try again below to create a code snippet in HTML.

Inserting Code Snippets into HTML: Just use opening and closing tags around the code below, and insert whatever code you wish to display inside the opening and closing tags:

                           xpm 
                            pre 

                            pre 
                            xpm 
                         

What is your workspace like in real life? Clean? Messy?

• Coffee, candles, notebooks, pens, books, flowers. Clean.

Is your code a reflection of that?

• My code needs to be better formatted according to the principles here:
• Formatting and Indenting HTML

Book To Read on Clean Code

Testing

                            function testSum(){
                                var expected = 7
                                var actual = sum(5, 2)
                            
                                if (actual != expected) {
                                    console.log("It's broken..")
                                } else {
                                    console.log("It works!")
                                }
                         

Have a go at writing a "sum" function below that would make the above function print out "It works!":

                                function addTwoNumbers(x, y) {
                                    return x + y;
                                  }
                                  console.log(addTwoNumbers(5, 2));
                             

                        function addTwoNumbers(x, y) {
                            return x + y;
                          }
                          
                          function testAddTwoNumbers() {
                            var x = 5;
                            var y = 2;
                            var sum1 = x + y;
                            var sum2 = addTwoNumbers(x, y);
                          
                            console.log('addTwoNumbers() should return the sum of its two parameters.');
                            console.log('Expect ' + sum1 + ' to equal ' + sum2 + '.');
                            
                            if ( sum1 === sum2 ) 
                              return console.log("It works!");
                            
                            console.log("It's broken..");
                          }
                          
                          testAddTwoNumbers();
                             

Do you think you would prefer using Test Driven Development? Why?

What is Test Driven Development (TDD)?

TDD is a particular way of doing code development as a whole. It involves starting with the big picture and writing your tests before you write your code.

This way of coding means you have to work out what you intend for the code to do and what smaller things need to happen to achieve this before jumping into writing it. Tests are then written that match this intent for your project.

You don't need to have written tests for your whole application before you start building, but in a TDD approach you would write the test/s for the next feature or function before you implement it.

Once the test is written, you can then write the code that makes the test pass. Because of this, TDD forgoes writing "nice" code - so long as it works to achieve the needs of the test, you're on the right track. This also means we can try a number of different methods to achieve the same goal as it doesn't matter how we get there, just that we do. Once the code works, we then go back and refactor it to make it more concise and readable.

See Testing with Node JS.

The article discusses a bit of theory concerning unit testing.

A unit test consists of three parts.

1. Arrange
2. Act
3. Assert

                        function addTwoNumbers(x, y) {
                            return x + y;
                          }
                          
                          function testAddTwoNumbers() {
                          
                            // 1. ARRANGE
                            var x = 5;
                            var y = 2;
                            var sum1 = x + y;
                          
                            // 2. ACT
                            var sum2 = addTwoNumbers(x, y);
                          
                            console.log('addTwoNumbers() should return the sum of its two parameters.');
                            console.log('Expect ' + sum1 + ' to equal ' + sum2 + '.');
                            
                          
                            // 3. ASSERT
                            if ( sum1 === sum2 ) 
                              return console.log('Passed.');
                            
                            console.log('Failed.');
                          }
                          
                          testAddTwoNumbers();
                        
                             

Assertions are a tool to do basic sanity checking for programmer errors. — Marijn Haverbeke, Eloquent JavaScript

Would I prefer using TDD to not using it?

This article gives good rationale behind why TDD is worthwhile in the long-run.
To summarise: Even if it seems like a large up-front investment, it 'pays dividends' in terms of preventing bugs; it documents code well; allows you to make changes earlier since you're more likely to be able to diagnose problems; it saves money in relation to the cost of development change over time; the saved time can then be invested into innovations and research. Lastly, it helps you to avoid scope creep - any unexpected growth in the scope of work which leads to delays in project delivery.

Another article on Unit Testing

Kata

How did you find using repl.it in practice? Confusing? Useful?

What is repl.it?

• Repl.it is a free IDE (integrated development environment) that allows users to write their own programs and code in dozens of different languages. While traditional IDEs are software programs downloaded to a computer, Repl.it is completely web browser-based and can be accessed from any internet-enabled device such as a phone, tablet, or computer. Users can access the software by typing the name directly into their browser, www.repl.it.

From a software engineer (with whom I'm in agreement):

• I use Repl.it almost every day and am very happy it exists and is growing. I like that their focus doesn't stray away with distractions of other possibly useful links.
• It's really there for you to practice, test, build, and deploy. Looking forward to the future or Repl.it.
• Pros: Ease of use, straightforward, useful, fun to explore
• Cons: none
• I like the instant feedback and error messages, it makes it easier to know where you've gone wrong in terms of feedback and how to 'course correct.'

Was it helpful to look at the tests while coding the kata?

• Yes! For example, in the replit below, if you scroll down in index.js you can see some examples of the error messages which come up. Essentially, in this case, we want our code to return TRUE in order to move onto the next stage. If you have successfully applied the correct values to the right property, then the programme will finally console.log (print out, in this case).

                            console.log("Here is your final terah object:")
                                console.log(terah)
                                

Here is a link to my replit page: Manipulating JS Objects

Was it helpful to look at the tests while coding the kata?

What problem solving techniques did you implement in your coding flow?

Please click here for my answers - This link leads to my Notion Notes on Manipulating JS Objects

What was the most challenging part of Super FizzBuzz for you?

Some questions I had (and conversation) related to this challenge:

• I'm trying to figure out how to solve fizzbuzz using arrays. I don't understand why you'd want to do it in terms of arrays? Have googled some examples online but they're not using arrays... For example, I understand how this functions:

Write a program that prints the numbers from 1 to 100. But for multiples of three print “Fizz” instead of the number and for the multiples of five print “Buzz”. For numbers which are multiples of both three and five print “FizzBuzz”.

Sounds easy enough, right?

Since we just need to loop through each number from 1 to 100, one of the simplest FizzBuzz solution can be achieved with a for loop:

                        for (let i=1; i <= 100; i++){
                            if (i % 15 == 0) console.log("FizzBuzz");
                            else if (i % 3 == 0) console.log("Fizz");
                            else if (i % 5 == 0) console.log("Buzz");
                            else console.log(i);
                        }

                            

My Thinking Process:

A Conversation

Did you want to change and refactor your code once you were finished?

What is code refactoring?

Final Reflections - Sprint Four

In addition to the challenge specific reflections, answer the following questions:

How confident are you with each of the Learning Competencies?

☑️ = Confident

⚠️ = Needs more work.

• Describe how neuroplasticity is relevant to learning ☑️
• Describe what Growth Mindset is and why it is important ☑️
• Discussed your understanding about Neuroplasticity and Growth Mindset and how it influences your learning ☑️
• Published that discussion as a personal blog ☑️
• What code readability is. ☑️
• Why it's an important skill to have as a developer. ☑️
• What code readability habits you can start building on today. ☑️
• Create readable code by practising indentation and formatting. ☑️
• Access, use and have a basic understanding of the website Repl.it for your Kata in Sprint 4. ☑️
• Why problem solving is an important skill to have as a developer. ☑️
• A variety of problem solving techniques you can start using today (starting with pseudocode). ☑️
• Define local variables in JavaScript ☑️
• Create objects of different types in JavaScript ☑️
• Create and add objects to an array in JavaScript ☑️
• Use pre-written tests to drive development ☑️ ⚠️
• Use strings, integers, arrays, functions ☑️ ⚠️
• Use if/else or switch statements, string methods, for loops ☑️ - Switch statements needs work.
• Define local variables in JavaScript ☑️
• Define functions in JavaScript ☑️ - needs work with complex functions.
• Create, add properties to, delete properties from, and access values in object literals ⚠️
• Research and use built-in JavaScript methods
• Use the built-in Array methods:
  • Map ⚠️
  • Filter ⚠️
  • Find ⚠️
  • Join ⚠️
• Use the built-in String methods:
  • Split ⚠️
  • ToUpperCase ⚠️

Which parts of the sprint made you feel smart?

• When I can solve problems quickly it feels good.

Which parts of this sprint made you un-smart?

• When I tried to solve a problem, I didn't realize that I wasn't choosing the easiest option in terms of solving it.
• Sometimes it is only in hindsight (after I see an elegant solution to a problem), that is appears obvious and I understand how it works.
• I would like to be able to think and create elegant solutions myself, and I assume this must come with practice and experience. Perhaps it's not an inherent thinking process but it can be learned.

How did you look after yourself this sprint (stretching, breaks, rewards, etc)?

• I struggled through some Javascript challenges for hours; most of the time feeling frustrated, confused, and doubtful of my abilities.
• I realised that instead of focusing my energy toward what wasn't working, or on negative self-talk, I could have used this energy to focus on solving the problem. This was when I went for a run and gave myself the weekend off, even though I hadn't finished sprint 4. I'm glad I got some rest and I see this as necessary, not as a luxury.
• I had a conversation with a student in the course and we agree that learning Javascript in a bootcamp/crash-course style is a bit like trying to learn German in a month. One of the important and underrated 'tools' in language (and for any kind of learning), is to do it in a relaxed manner. This week I am taking the pressure off myself so I can free-up my pre-frontal cortex. I aim to enjoy the learning process more in sprint 5.
• I read alot of fiction this week, and researched the benefits of Imagery - how imagery affects our autonomic nervous system and changes our physiological functioning. The brain registers sensory imaginational experience as similar to a lived experience. In general, I exercise and keep a regular sleep schedule.

If you could send a time-traveling text message back to yourself at the start of this sprint, what would it say?

• I would say: "Hey, you're probably going to experience some difficulty with the challenges, at times you will doubt yourself, feel frustrated and emotional. Know that this is OK, and that solving problems is certainly not always going to be easy! Javascript will be the tricky part but I know you're capable of conquering it." In part, this is what a friend of mine tells me. I'm so thankful to her! ❤️