General Coding Tips

Conclusions made from reviewing Udacity students’ code (for any level programmer).

  • Simpler is better.  Sometimes highly intelligent people write convoluted code. I think they feel the complexity must reflect their intelligence. However the downside is this makes the code harder to share and harder for another programmer to debug. The best code I’ve seen balances readability with abstraction and conciseness. Sometimes super abstract code is harder to understand or is error prone because it doesn’t handle all basic use cases.

 

  • Don’t code for yourself, code for the next programmer. This is closely related to the first point. But it speaks to items of consideration like including just enough inline comments and providing readable code. Writing code which is as clear as possible is considerate to those who share your code. This is reflecting a concept that as a programmer, you have 2 types of users (the application user and developers who work with your code base).
Advertisements

Tips for Young Programmers

As a Code Reviewer for Udacity, I go over a lot of students’ code. These are some observations based on common patterns.

  • Make sure to understand requirements. A lot of students are in a hurry to turn in the solution and get to the next assignment. Sometimes assumptions are made about the requirements or the student revises the requirements to what they think the app should behave like. Making assumptions takes more time to fix in the long run. Ask questions and get clarifications before you start to plan the solution.

 

  • Get the basics right first, then add enhancements. A minority of students are eager to show off nice to have enhancements like design or added features or complex interactions. But sometimes this extra effort is made before basic requirements have been met. Make a checklist and meet the core requirements first. Then add special features. Then refactor. Sometimes overly abstracted code leads to more bugs. Test everything on your checklist.

 

  • Try to code without libraries at first (as much as possible). Try to code with vanilla JavaScript before frameworks. Try to code with plain CSS before Bootstrap/Sass. By all means, learn the JS frameworks and CSS pre-compilers and accompanying libraries. But try to code everything by hand first (for ex. sometimes using a library to handle forms in react or redux abstracts the logic that makes it difficult to troubleshoot when an input handler goes wrong).

 

  • Show that you care about your work. Looking at someone’s code and app UI/interactions, it is quickly obvious how much pride the coder takes in their work. It is clear when the student is just trying to pass or is truly bringing their A game. When taking a course, really try to learn the best practices and ask questions. Skimming through a course (even when busy with a full-time job) is not really getting value out of the experience. Take the time to learn to do the job right during a class because frequently when the skills are put to use in a job, there may not be enough time to dot all your i’s and cross all your t’s. You’ll want to know all the tradeoffs you are making and why.

 

Summer Reflections

Green anole

Green anole

“Adventure. Excitement. A Jedi craves not these things.” Yoda – The Empire Strikes Back

This is a summary of my reflections on what was learned this summer. Some things were learned explicitly but I think the items that will stay with me were learned implicitly (by observing how others worked).

Technical

  • The need to have more depth in my area of knowledge (currently JavaScript: with some emphasis on React/Redux) (KD)
  • When maintaining an app, it is a good idea to read the existing code a bit more thoroughly (understanding the code line by line) (KD)
  • The need to be better about refactoring code before requesting a review (MT)
  • The need for improved code error handling (MT)
  • The need for improved definition of use cases (being more thorough about thinking out typical input/output scenarios before coding) (MT)
  • The argument for making atomic commits (MT)

Social

  • Relative to soft skills like making people happy or making people feel comfortable, coding is a relatively easy task
  • Also communication sometimes feels hard compared to coding

Small Miracles and D’oh Moments

The two memorable events of the past week were:

  • Getting my first patch for Firefox Nightly approved
  • Having a D’oh programming moment with my mentor about error handling

About the Nightly patch, I must admit that the experience feels so surreal that it really hasn’t registered emotionally. All I can recognize in my head is that the source code for Nightly is immense and the change I contributed feels molecular relative to an ocean. My mentor and a group member provided immense help in guiding me through the setup and review process.

Years ago, I worked as a Technical Writer for different enterprise business applications and had this sort of outsider’s feeling that the actual event of a software release is like a small miracle. That it is possible to produce a working piece of software that combines years of work with the ongoing changes of so many hands, well, it is really something amazing. Thinking about the Nightly releases reminds me of this.

About the D’oh moment, there was a point in my coding process when I had to troubleshoot an unexpected configuration change in the application. My mentor was trying to help me troubleshoot. The irc convo went something like:

>cch5ng: the error looks like *****. but when I manually update the configs it gets resolved. it still fails in the automated tests though.

>mentor: it looks like the code is blowing up at line ***.

>cch5ng: for some reason the automated test doesn’t pick up on the latest config changes.

>mentor: it looks like the code is blowing up at line ***.

>cch5ng: blah blah blah blah blah blah…

>mentor: it looks like the code is blowing up at line ***.

>cch5ng: ummm, do you mean I should be adding some error handling there for a missing config or unexpected data response?

Lessons learned:

  • Try to be better about defining the cases where error handling should be defined up front
  • Also separately: try to be better about defining the use cases; for ex. be thorough in the definition of different input states the code may need to handle
  • (Tip) When waiting for automated tests or build processes to complete, this could be a time to work on a blog…

Mozilla All Hands Meeting

Mozilla Web Compatibility group

Mozilla Web Compatibility group (All Hands Summer 2017). Photo by Dennis Schubert. CC by SA-2.0.

Summary

  • I enjoyed having a chance to meet everyone in person, especially those I only knew through their github handles when I was previously a contributor
  • I’m grateful to Mozilla for their generosity with having the interns attend
  • I’m grateful to the entire Web Compatibility group for being kind to me (and Bea, co-intern); in particular Mike T. was extremely generous with his time and planning for everyone to have mornings and evenings filled with interesting things to do
  • Additional thanks to everyone in the group for the generosity of their time and knowledge share (in particular Karl, Tom, and Guillaume)

Highlights

  • We had an interesting impromptu talk about running functional tests for webcompat.com (Bea clarified the use of running the server in test mode for required fixture files); quote of the week: “This is like space…”
  • Enjoyed listening to all of the engineering group presentations on the last day (especially the Software Architecture group which had clearly articulated slides)
  • Enjoyed Espresso ice cream at Ghiradelli Chocolate shop and jogging through Golden Gate Park (although I could not walk down stairs properly for the remainder of the week)

Group Appreciations

  • Adam: very down to earth and pleasant to chat with
  • Bea: very fun, understanding, and smart to boot
  • Dennis: wickedly funny and smart
  • Eric: pragmatic and interesting to chat with
  • Guillaume: a very nice sense of humor and patient with my questions
  • Karl: a good listener/reader (thank you), smart teacher, investigative reporter of code, and a strong work ethic
  • Mike: makes being a leader look easy, makes big things happen, patient with my D’OH coding moments (more details in a future blog)
  • Ola: humorous, intelligent, and productive; a bold thinker
  • Tom: balances a sense of humility, confidence, and intelligence in his communications; service-oriented in his work outlook

One general observation about the group is that everyone is highly technical but also quite verbally articulate. There is a very interesting balance of qualities…

Coding: The Good, The Bad, and The Ugly

Recently my mentor, taught me about how to conceptualize programming solutions at different levels. In my recent experience, I was used to developing fast hack solutions which I feel is not correct but given short deadlines, I felt little choice about. But instead of thinking about a problem as having only a hack solution or an ideal world solution, my mentor suggested considering the following:

  • The fast and hackey solution (AKA The Bad). Sometimes this is not a bad solution but some time should be taken to document why/how it was done and how it may be refactored when time permits.
  • The middle ground solution (AKA The Ugly… OK, it is more Middle than Ugly). This is often an ideal solution.
  • The ideal world solution (AKA The Good). This is like a “perfect” programming solution (if you had unlimited time and resources). Most likely this solution is going to going to have maximum flexibility for current and future use cases.

Recent Problem and Application

Recently I was working on a webcompat.com issue where there were some record types returned in github issue searches that should be filtered out. The solution that I came up with doesn’t exactly fit within the 3 categories described above (maybe it is somewhere between the hackey solution and the middle solution).

Since the data was coming from 2 Github API types, 2 approaches were needed:

  • For the Github search API, it is possible to intercept the user’s search query, append a custom string (negative label filter since the undesired data had a specific Github label attached) and send the resulting query with the Github API request
  • For the Github issues API, it is hypothetically possible to filter the Github API’s returned JSON results using a JavaScript function. This is not an ideal solution because it causes other issues (such as throwing off the expected records count per page) but it is a possible line of thought for exploration.

Resources

Flexbox vs CSS Grid

The purpose of this blog post is to compare and contrast Flexbox and CSS Grid. These are a few points for comparison:

  • How to conceptualize and plan layout
  • Ideal use case scenarios
  • Ease of use

Caveat: My approach to web development is fairly quick and dirty, having come from more startup type experiences (as Tech Writer and FE Dev contractor) than not. As a result, my biases are towards learning the minimal concepts necessary to get about 80% typical use cases done.

How to Conceptualize/Plan Layout with Flexbox

When planning out one responsive layout design in both Flexbox and CSS Grid, I felt like the main difference for thinking about Flexbox were the ideas of:

  • content container
  • how data should flow through a content container

These are some sketches used to visualize how the grid content would flow across breakpoints.

wireframe for flexbox design (mobile)

Wireframe sketch for flexbox responsive design (mobile)

wireframe sketch for flexbox design (tablet)

Wireframe sketch for flexbox responsive design (tablet)

wireframe sketch for flexbox design (desktop)

Wireframe sketch for flexbox responsive design (desktop)

By scanning the planning sketches hopefully you could get an idea that all that was necessary was to:

  • understand the number of columns per view (also the relative proportion of space needed by each column)
  • understand how content should lay out within the column
  • understand how the repeating pattern of data should display

How to Conceptualize/Plan Layout with CSS Grid

For CSS Grid, I felt like it was more important to sketch out a precise grid, as though the webpage were like a piece of graph paper and I had to lay out the skeleton that would support the content.

wireframe for CSS grid design (tablet)

Wireframe sketch for responsive CSS grid design (tablet)

Note: To be technically correct for a 2 column grid with margins (far left and far right), this should be a 4 column diagram. The far left and far right columns would actually be empty spacers. The resulting vertical line count would be 1-2-3-4-5.

TODO: redraw the grids with proper columns

 

Ideal Use Case Scenarios

My belief is that flexbox is a better choice when the required grid is relatively simple and when the data to be displayed is dynamic (for example, coming from a database and the total number of records returned from a query is not always constant).

On the other hand, if the required grid is relatively complex and the desired design layout needs to be pixel perfect, CSS Grid allows for a more granular level of control. Also if the data to be displayed is static, CSS Grid could be an option.

Ease of Use

Generally my preferred tool would be flexbox because the same CSS would easily scale to a dynamic size of data.

In contrast, I felt with CSS grid, there would be a bit of calculation and scripting required to make the CSS able to support a dynamic size of data. See CSS in the sample source (about line 60 and later).

What do you think? If it seems like CSS grid is more versatile, please explain your use case in the comments.

Examples

Flexbox example: Demo | Source

CSS Grid example: Demo | Source

 

Resources

https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout

https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Box_Alignment_in_CSS_Grid_Layout

https://gridbyexample.com/ (not used for this article but a good one)

For Flexbox resources, please see a previous article.