code.mechanics

100 Days of Swift Day 1

2023-02-05T16:00:00+00:00

It’s been a weekend of distraction, and I was hoping to be well past Day 1 videos.

TBH, I may have to fall back to a book or text of some sort. These youtube videos seem to be overly long and so far have not done much more than install Swift Playground.

I’ll keep at it for a little bit longer based on all the positive comments I’ve read on this series - but hope the pace picks up.

100 Days of Swift Day 3,4,5,6

2023-02-05T16:00:00+00:00

OK, so I missed the forest for the trees or however. Or, I’m just part dumb-ass.

I was following a YouTube playlist, but came to realize 100 Days of SwiftUI has all the videos transcribed on their site, making for a vast speed-up in covering the material.

So, I withdraw my complaint about slow speed - I can process the material at my own pace on https://www.hackingwithswift.com/100/swiftui

Things that are sorta interesting

I do like the strong type checking.
- After 4 years in largely Python-land, type hints are no substitute for strong type checking
Introduction to concept like ReversedCollection that wraps the base class / collection without having to re-allocate space
Nice introducing Sets early and mention of speed.
- I mean Set behavior was anticipated, but goot for the course to mention them early and get new folks thinking in terms of optimizations.
Enums
- Better than Pythons’s implementation I think, but using case is … odd to me.
- Like that they are internally stored as primitive
Constants can be assigned after declaration

OK, that is it for this blog post - I don’t want to spend a lot of time doing the ‘social media’ aspect of the course, but like the idea of it keeps my honest with my own progress.

100 Days of Swift Day 0

2023-02-03T16:00:00+00:00

Inspiration

I - just yesterday - realized I may have some opportunity to turn previous experience into an opportunity… to develop a specific application used on an iPad.

But what do I know, I’ve never written a Swift App.

Time to dig in.

Enter 100 Days of SwiftUI

Sadly, as with many things in life - my first stop on the Swift journey was to check Reddit. Join r/swift … check Read the sidebar of r/swift … check

Oh, they recommend 100 Days of SwiftUI for beginners … Interesting.

Check out 100 Days of SwiftUI and watch the intro … I’ve been here before, but agree that posting consistent updates to social media is a good way to self motivate.

So here we are

So here I am, making my first blog entry to hold myself accountable to my own progress.

Next steps seem to be installing the Swift Playground and on to Lesson #2.

Never stop learning!

On Software Quality & Requirements

2021-11-19T16:00:00+00:00

Inspiration

My team’s applications are the product of dozens - if not hundreds - of different engineers contributions going back to 2015. That is to say, we’re a fairly mature product being used by hundreds of other engineers every day. But, how do measure quality? We report all sorts of metrics upstream to management, but nowhere in there is a metric that measures the quality of our code. Oh, we do have some checks like cyclomatic complexity - and other checks by linters and tools to enforce conformance to best practices, etc.

What we do have is self-acknowledged tech debt, a backlog of Jira Issues, various TODOs scattered around in the code base - and overflowing good intentions to address these just as soon as the stars align to allow us to free up developer time to start tackling the backlog.

That is not to say me and my teammates don’t do our best to address issues when we find them in the course of working our tickets - but more that any improvement to code quality is more of a side-effect of writing new functionality into existing code, than the goal itself.

What is Quality?

Paraphrasing the definition as found in both ISO 9000, PMBOK, and elsewhere:

…the degree in which a set of inherent characteristics of an object fulfills requirements.

It’s important to distinguish quality from grade when used as a metric for fit-for-purpose. Quality is the degree in which a product fulfulls its promises and obligations, where Grade is the category of the product.

Requirements: the missing ingredient of software quality

As software engineers, we write code, unit tests, functional tests, integration tests all in the spirit of producing high quality software. We will create Jira tickets that detail user stories and acceptance criteria.

But, where do we track and trace requirements? Some companies have compliance obligations and will employ formal requirement documentation and tracing. However, this is the exception rather than the rule. It adds a layer of complexity and expense - both in hard dollars and developer time.

However, it’s right there in the definition of quality - how well does our software fulfill the requirements? Sure, requirements don’t have to be recorded - but how well are we actual tracking / revisiting old requirements. Often our source of truth for requirements related to the current codebase is that senior engineer who was there the last time this module was changed and remembers something - vaguely - about the original request. So, we end up implementing what user A asked for without realizing the negative impact it will have on user B.

What is needed (Opinionated)

Requirements management tools exist, but most of us don’t bother using them. It’s too much book-keeping that is not seen as clear added value.

Ultimately, we have to convince ourselves, our peers, and our managers that there’s value to formal requirement tracking for any long-lived application under active development. We need to be able to be agile (lower case agile - not opening the door to the whole Agile discussion here), but we need something to hold us accountible to the decisions made yesterday, but yet allow those decisions to be further refined or changed today.

Github code review tunnel-vision

2021-10-21T16:00:00+00:00

The problem with github’s code reviews

Today’s soapbox: Github’s code review tool creates tunnel vision

I see this happening a lot: a PR on github is reviewed only within the extent of the changes. That is to say, “Yep, the code you wrote LGTM” without considering the context of the larger code base.

Today’s example was the addition of new logic with a corresponding (new) boolean flag parameter to control basic logic within the function. All that’s fine and good - but once I opened the file up in an actual editor and started tracing calls upstream and downstream, we quickly identify the new boolean flag is superflous, and what’s more - we’ve got another parameter that now mirrors an existing object attribute - so why are we still passing it around?

Also, we can’t comment on lines outside the diff itself - so drawing attention to something else, or questioning an existing (but un-changed) block of code isn’t the easiest to do. We end up with comments like

Not your change, but L187-190 above should be changed to reflect new object attribute.

But the bigger problem - and original gripe - is the tunnel-vision. We’re rushing these patches through review without spending time looking at them with a more holistic approach and when we finish our review with +1 LGTM, we really haven’t considered the code change in the bigger picture - are we duplicating functionality? Is this optimal fix, or are we just doing what is most convenient here because to do it correctly, we really need to refactor this module and nobody’s got time for that? etc.

For me, I’m going to make a point to pull down more code reviews locally and spend the time it takes to check better upstream and downstream - especially when the entirety of the change isn’t within a single function.

Partitioning data with sentinel value using Pandas

2021-03-02T16:00:00+00:00

The problem

I have a collection of sensor readings / telemetry that I want to partition into subsets based on the detection of a sentinel value. For this case, imagine a collection of power readings for a motor running a conveyor belt in a factory. When a batch is being produced, the conveyor belt runs continuously. The belt motor is powered off during process change-overs.

The motor drive is polled once per minute and instantaneous power draw is saved to database along with other metrics from elsewhere in the process.

The solution

It is easier to show than explain… The gist is located here

Mentor Collective @ Oregon State Univ PostBacc CS

2021-02-14T17:00:00+00:00

When I decided to make a career change, I went back for a second Bachelors - this time in Computer Science through the Oregon State University PostBacc Computer Science program. At the time, I was in one of the early cohorts to graduate and since then, the program has grown substantially. One of the additions in recent years has been a partnership with Mentor Collective to pair graduates with current students in a mentoring relationship.

For Winter ‘21 term, I’ve been paired with 3 student in the program - which brings my total pairings to around 10. But what prompted this post is the meeting I had with one of my mentees this past week. He is far along in the program - and has completed 2 sucessful internships and already has accepted a job at one of the FAANG companies pending his graduation. For convenience, and to avoid his real name, I will call him ‘Chris’.

To be honest, my impression on reading Chris’s introduction email and browsing his LinkedIn was “What in the world can I possibly contribute here?”. He’s clearly on a very sucessful track.

As I’ve gotten to know Chris better, it is evident that he’s one of the students with a clear sense of ownership and initiative when it comes to his career. While most of the mentees I’ve had over the past 2 years are willing to talk with some prompting, and have occassionally reached out with certain requests - resume feedback, etc. - Chris almost immediately scheduled a 15 minute Google Meet for us to talk. That 15 minutes turned into nearly an hour long conversation.

Chris had clearly been thinking about his pending graduation and life as a ‘real’ software developer in the near future and came prepared with a list of questions - which were all mainly centered on wanting to hear my experiences in industry. He fully understood that my own answers here might not reflect what he runs into in his upcoming role, but was very keen to hear my own take on topics like:

Comparing my experience at Garmin with what I’m doing now at Intel
- What are differences in team organization and size?
- What do I feel were important differences in management’s organization?
- How did I feel about making a switch from embedded to more of a full-stack environment?
- Which company did I enjoy working at the most and why?
How did my family adjust to relocations?
What did I think of benefit packages and differences?

He took ownership of the mentoring relationship

This was my biggest take-away - Chris came in to the mentoring program knowing what he wanted out of it, and was prepared to drive the relationship forward. So many students seem to sign up and expect to be spoon-fed by their mentor - but that’s not how these relationships are designed to work. Sure, I can check in periodically and make sure that the student is proceeding OK scholastically, but that’s not the point of building a mentor relationship.

A mentor is a resource for the mentee. We’re another tool in your toolbelt, but it’s up to the mentee to decide when and where to apply the tool and for what benefit.

Intercepting python module call()

2021-02-10T20:27:14+00:00

Python provides the __call__() magic method to allow an object instance to behave as a function in that you could now call the object directly.

I ran into the case where we needed to override a value previously initialized instance variable being used within the __call__() in a 3rd party module - specifically the ProxyFix middleware in the Werkzeug library. I’ll keep this example more generic though - I wanted to set up the scenario though in that I really don’t want replace the original class’s __call__() with my own, but I want to alter some of the instance variables that control the call’s behavior.

The solution is straight forward:

Override the class
In child class, modify the instance variable
call the rest of the logic in base class via super.__call__()

Here’s a simple gist with example:

Note in that gist, the original instance value has been completely replaced, but would be easy enough to save off and restore.

Code comments as knowledge transfer

2021-01-09T20:00:00+00:00

Uncle Bob vs. Me

In another post: [Clean Code by R. Martin]/computerscience/books/2020/12/27/book-notes-martin-clean-code.html, I am keeping some running notes as I re-read the Uncle Bob’s well known book.

Chapter 4: Comments made me start questioning myself, and my own use of comments. Along the lines of “Hello, my name is Vaughan, and I am a code commenter.” Do I really have a problem and am I hiding it from myself?

Possibly, but on closer inspection perhaps it is not as bad as it appears.

Where Clean Code gets it right

In principle I agree with everything Robert Martin has put into the Comments chapter:

“Don’t comment bad code - rewrite it” - Kernigham & Plaugher
“The proper use of comments is to compensate for our failure to express ourself in code.” - Robert Martin
Comments lie
Become maintainabilty issue - code evolves, comments don’t
Code is the source of truth
Spend effort to minimize comments

I don’t disagree with any of this, and when I find myself writing a comment, I always try to take a second pass to eliminate the need for the comment. Often a little refactoring goes a long way to remove the need for a comment.

The missing case for comments: Knowledge Capture & Transfer

I am biased by the code bases I’ve worked on professionally. They’ve been mature (read: long-lived) code bases that are still constantly evolving as technologies and business needs evolve.

What I’ve found in practice is that comments are invaluable for knowledge transfer.

As software developers, we find ourselves translating business needs and customer requirements to code. Sometimes it is very straightforward, but many times it is not. We have to develop an understanding of the underlying business reasons and user expectations in the business domain, which we are likely not experts in ourselves. We do this by talking to the customers & users, other managers, doing our own research, etc.

At the end of this process, we are mentally holding a bunch a details that use to inform the writing of the code. Usually in a matter of days, weeks, and possibly months - we’ve become the subject matter expert on the dev team for the module we are working on.

Then one day the module is magically finished, merged into mainline, and we pick up a new ticket to start working, and move on with new issues. Before long, some other developer has to go work in that module we knew so much about, and learned the intricate details. Good comments can help this other developer (or even future us who has forgotten some of the details) understand the reasoning and implementation choices that were made at the time.

Example: Realistic depiction of runway thresholds on graphical flight displays

This is one of the issues I worked at Garmin. At the time, Garmin’s flight displays had a generic visualization of 8 runway threshold stripes that was used on all runways. It helped make the runway displayed on the moving map “look” like a runway.

In the quest for continual product improvement, somebody realized that in fact, “real world” runway markings were much more complicated - and different markings conveyed different information to the pilot about to land on the runway.

In the process of implementing the feature improvement - which started out as the simple request “Runway threshold stripes should correctly match the use of stripes on the actual runway”, I ended up learning quite a bit about runway markings. I learned a lot of details from the FAA’s AC150/5300 Airport Design Standards.

The first implementation of the new logic was merged with much rejoicing… until a few weeks later feedback started coming in from the test pilots along of the lines of “the new runway lines seem to dance and flash as we land, it is distracting”. That was indeed a problem - so back to the drawing board.

To spare the details, we had to make changes and compromises within the actual FAA standards and what we could do to get a clear, non-distracting visualization on the display. The FAA standards are applied to runways 50 to 200+ feet wide, and the display has to work with a finite number of pixels.

At the end of the day, the module was commented with all sorts of information for the next person that had to deal with it:

Links to the appropriate FAA standards online
- Yes, these could change over time, but at least they provide a starting point for the next developer that needs to get up to speed.
Explanations of design choices. Examples:
- Why I only generated a dynamic texture for half the runway width (because we can mirror-image it)
- A brief history of why the ‘obviously simpler’ approach failed.
  - As we don’t want history to repeat itself a couple of years later when somebody say “Oh, this can be done quicker and simpler if we do a, b, and c” Been there, tried that, results were not acceptable.
- Why we fall back to using a lower-resolution static image at certain zoom ranges
- How projects consuming the library can use tunables to configure the behaviour for the parameters of their particular display.
- How the stripe image asset was developed and importance of design choices that support a texture that has sufficient anti-aliasing not to flicker
- Math employed to properly center the texture on our world cordinate system
- and so on.

All this provides a lattice of information that some other developer new to the module could easily leverage to minimize time and effort to get up to speed with the implementation provided by the module. Lack of sufficient documentation would be called out by teammates during review - they knew it could be them working in that module next.

Closing: Don’t consider comments as second-class citizens

Robert Martin’s advice on code comments is good and true, but runs the risk of deprecating the added value useful, informative, and well-considered comments can bring to software. Comments should carry the same weight as the code itself - they are not second-class citizens you should feel free to skim over as you maintain your code. Yes, they are a maintenance burden - so use discretion and think carefully about their use.

One of the first things Robert Martin mentions in Clean Code is the Boy Scout motto of “Leave the campground better than you found it”. In this context, think of good comments as that voice of experience you can leave for new campers to more quickly orient themselves on arriving at the campsite.

Book Notes: Clean Code by R. Martin

2020-12-27T16:00:00+00:00

I want to take another pass through Uncle Bob’s (a.k.a. Robert Martin) book, Clean Code.

A lot of my work lately has been trending towards overhaul & refactoring legacy modules that have been modified, patched, and Frakenstein’d for years. This typically starts with a new feature request, which seems simple enough on the surface - but once I get into the modules in question, some of the accrued technical debt means it’s not as simple as it could be.

I want to avoid giving the wrong impression though: I think our particular code base is in fairly average condition given its age, size, complexity, and number of contributors. It’s just time to bring some of the Boy Scout Rule he mentions right in Chapter 1: Leave the campground better than you found it.

Book Notes != Book Review

To be clear, the purpose of this post is a place to collect my own notes as I read through the book. Uncle Bob is going to explain some things that reasonate with me strongly, and probably there will be things I disagree with as well.

My goal is 1 chapter a every day or two, and I’ll just continually update this post until I’m finished. What I hope to produce in the end is a Cliff Notes-ish post that will be useful for me to circle back to in the future.

Chapters

1. Clean Code

LeBlanc’s law: Later equals never
- I need to remember this one for Kanban review and planning meetings when we kick the can.
- Corollary (or something): Perfect is the enemy of done
Various takes on the idea of Clean Code by big names in CS
Making code easier to read actually makes it easier to write
Boy Scout rule: Leave the campground better than you found it.

2. Meaningful Names

No suprises here, agree with everything, a couple of highlighted notes:

Clarity is king
Don’t be afraid to rename if you come up with something better
Don’t add gratuitous context

This is something every team I’ve been on has been about the same stage of acceptance: The benefit of longer / more descriptive names for everything across the board outweighs the cost of the longer name. Still, if you can be concise and short - that’s even better. Just don’t be short named and vague.

3. Functions

Keep them small!
Functions should do one thing, do it well, and do it only
- “If a function does only those steps that are one level below the stated name of the function, then the function is doing one thing”
Code should read like a top-down narrative
By their nature, switch statements do N things
Use descriptive names for functions
- “A long descriptive name is better than a long descriptive comment”
Ideal number of arguments is 0, followed by 1, then 2.
- Boy, do I have a lot to work on here.
- more arguments = more testing / harder testing
- A boolean argument is really, really bad
  - Means the function does 2 things
  - IMO, maybe not that bad… essentially lets you choose a strategy - but I get his point.
Functions should not have side effects
- “Side effects are lies”
Function should do something or answer something - not both
Exceptions > Returning error codes
- Lets you separate error handling from happy path
- Error handling qualifies as “one thing” - so have error handling functions
DRY
Structured Programming - the old single entry / single exit:
- If functions are small, so what if you return early
- Personally, I like early bail outs when justified, it cuts the mental clutter of what the possible cases are by tying off loose ends early.
It is not natural to write code like this:
- Start with getting the logic down, then:
  - refactor! refactor! - try different things

Comments

“Don’t comment bad code - rewrite it” - Kernigham & Plaugher
“The proper use of comments is to compensate for our failure to express ourself in code.” - Uncle Bob
Comments lie
Become maintainabilty issue - code evolves, comments don’t
Code is the source of truth
Spend effort to minimize comments
Acceptable as Explanation of intent, warning of consequences

The chapter goes into a lot more details and specific examples that are worthwhile to review, but the above bullets capture the essence.

Formatting

Formatting is important
… is about communcation
Vertical density implies close associations
Declare variables as close to their useage as possible
Instance variables should be declared at top of class
Dependent functions should be vertically close
Functions with high conceptual affinity should be close
Vertical ordering -> call dependencies should point downward
Horizontal formatting - 80 chars is arbitrily short, but don’t go too long either
Indentation helps visualize structure, and also too deeply nested code
Follow team rules, use static analysis

code.mechanics

100 Days of Swift Day 1

100 Days of Swift Day 3,4,5,6

Things that are sorta interesting

100 Days of Swift Day 0

Inspiration

Enter 100 Days of SwiftUI

So here we are

On Software Quality & Requirements

Inspiration

What is Quality?

Requirements: the missing ingredient of software quality

What is needed (Opinionated)

Github code review tunnel-vision

The problem with github’s code reviews

Partitioning data with sentinel value using Pandas

The problem

The solution

Mentor Collective @ Oregon State Univ PostBacc CS

He took ownership of the mentoring relationship

Intercepting python module __call__()

Code comments as knowledge transfer

Uncle Bob vs. Me

Where Clean Code gets it right

The missing case for comments: Knowledge Capture & Transfer

Example: Realistic depiction of runway thresholds on graphical flight displays

Closing: Don’t consider comments as second-class citizens

Book Notes: Clean Code by R. Martin

Book Notes != Book Review

Chapters

1. Clean Code

2. Meaningful Names

3. Functions

Comments

Formatting

Objects and Data Structures

Intercepting python module call()