The Power of PseudoCode

“Pseudocode” is a powerful way to write and document software. Put simply Pseudocode is just plain english text describing what the code should do – it is not actually code itself. I found this old-school screen cap on Google that describes nicely a few of the reasons why Pseudocode is great:

How to Write Pseudocode: 15 Steps (with Pictures) - wikiHow

The following is an example of what a good use of Pseudocode looks like. In this case I’ve written out the basics of a function to handle user logins:

/**
* login:
* 
* The purpose of this function is to attempt to login a user.
*
* Returns: 
* User record: On successful login or
* false: On error or failed login
*/
function login(username, password) 
{
    // TODO: Check for valid inputs to this function:

    // TODO: Get the user from the database:

    // TODO: Check the user is valid:

    // TODO: Check the user is not locked out:

    // TODO: Validate the user's password:

    // TODO: If the user passes all above checks and has a valid
    // password, then return their user record, otherwise 
    // return false:
}

As you can see we haven’t written real code. We really only wrote the skeleton of a function and then wrote out in plain english comments what our code will do.

The Benefits of Pseudocode

Why would you write out Pseudocode instead of just writing the code? Well there are a few reasons:

  1. Breaking Down the Problem: By writing out the basic steps to implement our function we have to think about the entire problem to be solved by the function. This helps us break down how the code should work and how it must work when there is bad input or an error.
  2. Specify the Interface: Pseudocode can help us to define the input and output of our function, class or code blocks. In the case of the example above we have to handle two cases – a successful login and a failed login, so we need to have returns for both. It also allows us to share our planned interface with other developers before we have written the code.
  3. Identify Opportunities for Reuse: For each of the high level steps of the function, we have a TODO line. In some cases we can identify through these steps items that could be made separate functions that could be reused. In the case of this example, there are at least 3 items that should be separate reusable functions.
  4. Find Gaps in Understanding: The final benefit of Pseudocode is that it can help you determine what you need to know that you don’t know right now. In our hypothetical example, after writing out the function it is clear we don’t really have a strategy for error handling and that needs to be addressed. Returning “false” when a login fails is OK – but does not communicate errors, or reasons why a user could not login. We won’t address it here, but proper error handling is definitely a topic for the future.

Actually Writing the Code

Taking into consideration our four points above we can actually write out or code by filling in the TODOs. We will do this with some basic operations and calls to external functions/libraries we either write or have available:

/**
* login_v2:
* 
* The purpose of this function is to attempt to login a user. 
* We've made some changes based on our thoughts so far.
*
* Returns: 
* User record: On successful login or
* false: On error or failed login
*/
async function login_v2(username, password) 
{
    // ------------------------------------------------------ 
    // Check for valid inputs to this function. 
    // ------------------------------------------------------ 
    if ((username != undefined) && (username != '') && 
        (password != undefined) && (password != ''))
    {
        return false;
    }

    // ------------------------------------------------------ 
    // Get the user from the database - this should be
    // a reusable function:
    // ------------------------------------------------------ 
    var the_user = await users_service.get_user_by_username(username);

    // ------------------------------------------------------ 
    // Check the user is valid and is not locked out:
    // ------------------------------------------------------ 
    if (the_user == undefined || the_user['status'] != 'VALID')
    {
        return false;
    } 

    // ------------------------------------------------------ 
    // Validate the user's password:
    // ------------------------------------------------------ 
    var valid_password = await users_service.validate_password(the_user['password'], password);

    // ------------------------------------------------------ 
    // If the user passes all above checks and has a
    // valid password, then return their user record, 
    // otherwise return false:
    // ------------------------------------------------------ 
    if (valid_password == true)
    {
        return the_user;
    }
    else
    {
        return false;
    }
}

A lot changed between our initial Pseudocode and what we have now. But, the key take away is that the code we added just filled in the pieces we created with our Pseudocode.

Creating/Using Reusable Functions

Most of the above is pretty simple code. It may or not be an optimal solution or example, but it is instructive. One key concept shown in this example is how Pseudocode can help you identify reusable code.

The “users_service” is an example of what I mentioned above. Pseudocode helps you find places where you will need to do something in other places – and the user operations in this function are exactly that. You will need to get user records frequently so write the code to do it once and reuse it. Similarly password checks may need to be used in multiple places, so write it once and reuse it.

Often times when I build code, I will define services to handle various pieces of functionality. One very common one I use is a “users_service” that handles all user operations – get, create, update, delete, search, and validate operations will all be part of the service.

Finding these places where you will want to create reuse-able code is one of the strong benefits of the exercise of Pseudocode. It will become very clear when you go through what code will be something you would want just here in this function vs. something you can use over and over.

Added Benefit: Code Documentation

Another great benefit of writing Pseudocode first before you write code is now you have code documentation already written. It’s already written as part of your Pseudocode. You just need to tweak it to match the actual code you have written as needed.

Some may say that the comments above are trivial and unneeded. To some extent that is true, but in this case we’re providing a simple example so the comments help.

Self Documenting Code is a LIE

I hold the VERY STRONG opinion that code comments are required and you can never have too many code comments.

I absolutely HATE the idea that code is “self documenting”. It’s not. Stop lying to yourself and your team.

Let me repeat myself. Your code is NOT self documenting. You, the original author of the code may have a complete understanding of it at the time. You or the poor bastard that comes behind you 18 months later will have no clue what you meant or what business rules you were using.

(Note: I’m not the only one who thinks this by any stretch. Here is another great article on the topic: https://medium.com/it-dead-inside/self-documenting-code-is-mostly-nonsense-1de5f593810f)

I’ve seen and had to work on code that is more than 10 years old many times. I’m talking about code running enterprise applications at billion dollar companies. Very rarely do these ancient applications have any code comments.

The worst example I can think of was a 21 year old PHP applicaiton. This code was initially written 5 major PHP versions ago. It has been heavily tweaked, changed, and refactored over the years. No one ever added code comments and so no one knows how it really works. Working on new functionality or making bug fixes takes forever because you have to read through a ton of code to figure out what is even going on.

This is the nightmare you create without code comments. Nightmares for whoever the poor bastard is that has to work on your code down the road. That poor bastard might be you by the way.

But by writing Pseudocode first, you already have a basis for code documentation and code comments. So, I advise that you do so, and continue to comment your code as it grows and evolves. You will thank me later. Your colleagues and folks who come behind you will thank you too.

Start Today

If you don’t already make a habit of writing out code in Pseudocode – try it out today, or the next time you are writing code. It will help you better understand and structure your code – plus it comes with the added benefit of having already written code comments to help you and any future developers who have to touch your code.

New Topic Area: Finance & Investing

I’ve decided to add a new topic area to my blog – Finance and Investing. I’ve made PLENTY of financial mistakes over the years, and I’m happy to say I’ve learned quite a bit from them.

One of my goals for most of my adult life is to be able to be financially independent so that I could retire early. I am proud to say I’m close to achieving that goal. I’m only 43 and I could retire in the next 2 or 3 years if I wanted to. I’m not sure I will ever want to stop working entirely because I enjoy it too much – but having the option is very nice.

Anyway, I hope to share some of the financial lessons, tips and tricks I’ve learned over the years here so that others may benefit.

Mentoring on Springboard

Earlier this year, I started working with Springboard as a Software Engineering Mentor. Springboard, for those who don’t know is an online learning platform that offers courses in a number of areas such as: UI Design, Data Science and of course Software Engineering.

I was drawn to Springboard because I liked their overall approach to teaching students, and the fact that they partner with students to help them find work when they complete the program.

Springboard Software Engineering Prep Course

Springboard offers 2 Software Engineering course options.

The first course is called the Software Engineering Career Track Prep program. The Prep program is designed to be a short 4-6 week introduction to software development. It covers basic concepts and uses JavaScript and Web development examples to help students dip their toes into writing software. For those folks who are interested in software and have never tried it this is a great way to find out if it is for you.

The Prep program starts very simple and builds on each lesson so that at the conclusion, you can create web pages and implement some basic dynamic functionality in JavaScript. At the conclusion there is a test that helps measure your progress and aptitude.

I have mentored a few dozen students through the Prep program. Almost all of the students I’ve worked with have enjoyed the course and found it really rewarding. There have been a few who learned that software is not something they understand and/or enjoy – and that is OK too. Writing software is not for everyone. It is much better to find out software is not the career for you after a small time and financial investment vs spending thousands of dollars or years of time only to realize you hate it.

Springboard Full Software Engineering Career Track

The second offering Springboard has for Software Engineering is the full Software Engineering Career Track. This is a much longer course meant to be completed over about 10 months.

Like the Prep program the full course starts out simple but quickly builds upon each lesson. After the first few weeks each student will be designing complete fully working web applications. Around the end of the first month, students will have built out a substantial web application that works well and mirrors a popular web site’s functionality.

Most students who complete the Prep program want to move on to the full Career Track and I encourage them to do so. Springboard has some flexible programs to make the course affordable and they really do care that you succeed. That is what drew me to work with them – the genuine desire and structure to ensure every student is successful.

Springboard is not just another code boot camp that’s a money grab operation. They are the real deal – they actually care about your success and they are offering a great program to teach you how to develop quality software.

Learn More about Springboard

Are you are interested in writing software as a career? If so it is well worth the time and financial investment to try a Springboard course.

Check out their programs at Springboard.com

If you are interested in becoming a mentor at Springboardclick here to learn more about their programs and how it works.

Refocusing and Rebuilding

I’ve had a blog site online for quite a while. I think it’s been something like 10 years now. I never spent a lot of time writing here, and really only used it to showcase some of my mobile app projects.

Image result for rebuilding icon"

Well, that’s going to be changing. Starting today, I will be focusing this blog on sharing some of the things I’ve learned over decades of developing software.

One key benefit to sharing my past work is that I can start to have a nice demo portfolio online for folks to see. One of the challenges of interviewing today is that everyone wants to see your code online. Some short sighted interviewers don’t realize that there is a LOT of software written that doesn’t end up being used by the general public. Or software that was online at one point and has since been removed. The vast majority of the software I’ve ever written is internal corporate software. Or, it’s the guts of a system that powers a public facing system. So, there’s nothing to “show”, really.

For example, one such system I wrote years ago at Southwest Gas was a system integration between their Interactive Voice Response (IVR) call system and their backend mainframes and databases. My code was used to connect callers to their accounts so they could get their payment, balance and other information via the phone. This system handled ~2 million requests per month flawlessly. So, yeah its a cool system, but unless you’re a natural gas customer in the US southwest, you’d never be able to see or use it.

Anyway, more to come in the future. I am going to do my best to make this a useful blog for developers and folks curious about software in general. Stay tuned!

Technical Interviewing is Hard

We have been doing a lot of technical interviewing lately trying to find new candidates for open positions. It has been challenging to say the least to find quality people. Even if we find quality people, they have often failed at a 2nd stage interview.

I came across this article in my daily reading today:

https://www.freecodecamp.org/news/you-will-randomly-bomb-technical-interviews-everyone-does-heres-the-data-44475806e32/

If you have to hire technical talent – take a few minutes to read the above, its worth the time. It speaks to the problems with technical interviewing today. It is spot on and addresses the problem of the interview itself. It is only a tiny window into the capabilities of the candidate. You need to talk to and interact with the candidate multiple times before you can really assess their skills.

In my interviews, I always want to make sure at least one other person interviews them separately. Ideally at least 3 separate interviews with different interviewers across at least 2 days. That way you can really get a sense for their skill and personality.

What about Coding Tests?

Experience shows me they are a waste of time. I’ve used them to hire. They did not predict whether a candidate could code at all.

I’ve done them for job interviews and failed them. Ha. Yeah, really. I’ve been coding for 36 years and have built every type of system under the sun. But, there have been cases where I’ve failed tests because the tests suck.

Yeah I said it coding tests SUCK.

Testing someone over an hour or two is meaningless. Testing their knowledge and usage of some obscure algorithm or some weird JavaScript library is not useful. If anything it can give you a false positive. Someone who can implement bubble sort really well is not necessarily even remotely a good developer.

Based on the stats I’ve seen most people are taking the tests are failing. So really, all you’re weeding out a ton of good candidates over some arbitrary test.

I don’t put a lot of stock in the automated coding tests that are becoming all the rage. Why?

  • They are often so contrived to be not relatable to the real world. Who cares if someone can recite and recreate quick sort in Go?
  • They can and are cheated, all the time. So if you get some one who aces the test – can you really trust the results?
  • The results aren’t trusted when someone DOES score well. Example: I’ve interviewed three times with a company. (Long story, but I did work with them and was offered a job 2 of the 3 times.). This company use the CCAT test – a standardized timed online test with 50 questions. I scored 47, 45 and 50/50 in my tests. All of these are very high like 98th percentile or higher results. Yet the company said they only do the test because process – no one cares about the results because they think people cheat the test. Yikes.
  • Automated tests almost always work with niche libraries within a technology, testing esoteric library knowledge and not coding knowledge.
  • Finally, online coding tests that aren’t simple, contrived examples, often expect you to build a complex application solution in an hour – and then you get judged on whatever piece you completed. Hiring managers should be interested in code quality, not raw coding speed.

So what is better? White boarding, discussion, and explanation. Ask your candidate to talk and walk through something they built. Ask for details. Then ask for more details. If they built it, and they truly understand it they will be able to describe it in detail, including how it was built, why decisions were made, and what problems they solved. White boarding and discussion can be far more informative of a person’s history and knowledge.

Candidates that can do that – are the ones you want to hire.