Introduction
While there is no one right way to code, if you do not take some time beforehand to prepare, plan, and strategize? You likely will hit major roadblocks, large code restructuring needs, and lost time fixing more bugs because of it.
I was honored to be invited to speak at Cisco Live in Cancun back in December 2018. For my talk, I decided to cover "How To Think Like A Programmer" as an introduction to how to more effectively and efficiently begin the coding process.
Writing code from scratch is like writing a paper. You need to know what goes in, how it should be structured, and then create your masterpiece.
The Process
While you are welcome to check out the 15-20 minute recording, the code, and the PowerPoint in the "Additional Links" section, this section will briefly outline the steps covered in the talk.
Step 1: Gathering Requirements
When gathering requirements, it is best to have a brainstorming session to cover anything and everything you would like your finished product to do. No idea is too big! In this day and age, "impossible" is impractical.
These requirements can come from your BU (business unit), PM (project manager), PO (product owner), or any stakeholder belonging to your project that has a say in what is needed.
Obviously you should for sure have the bare minimum requirements, but the more you have a vision of where you want to go? The easier it will be to structure your code to accommodate for those plans in the future.
If you fail to plan, you are planning to fail. Why? Because too often the future is not even outlined, so when you're ready to implement new features? You likely will have to do some major code refactoring (and thus bug fixing) because you did not plan for that kind of expansion.
What kind of requirements are you looking for in this phase?
- what the script will/can/should do
- resources required (particular language, access to APIs, etc)
- human resources that might be able to help (owners of APIs, other coders, etc)
- any code that can be reused
Keep in mind that while you will brainstorm a lot of ideas, you should first focus on the must have items (your base requirements). Everything else will be the nice to have items that should not take precedence over the required needs, but allow you to structure your code for future enhancements.
It would also be good to note that sometimes the business needs change and what was once a must have may become a nice to have and vice versa. This is why it's important to plan ahead and be flexible.
As part of the code provided at Cisco Live LATAM Dec 2018, you can check out step 1 for our rock, paper, scissors game here.
Step 2: Determining Your Base Functions
The first step to building out your "bare bones" framework is planning out your base functions' specifics.
Things to consider:
- what are the major milestones to complete this project? (iterable deliverables)
- what can be reused later by other programs?
- what might be reused later within the program?
- what goes in to the functions (if anything)?
- what will the functions do exactly?
- what will the functions return (if anything)?
Here is what was provided in the talk.
Step 3: Building Out Your "Bare Bones" Framework
Once you have outlined the base functions, now is the time to start building the framework. Each function will be empty for now, as you are not yet writing the logic to fill them. This is simply the "outline" of your project.
Here is what should be included in your "bare bones" framework functions:
- define the name in the header line with pass as the only command
- include docstring
- what does the function do?
- any required or options inputs?
- any output or data returned?
- begin using logging to show when you enter and exit said function
For example:
# python code
def func1():
"""
This will be where your docstring goes (documentation).
It will explain:
- what goes in (if anything)
- what the function will do
- what the function will return (if anything)
"""
pass
You will do this for every required piece. This not only allows for a good structure, but also for others to be able to work on your code at the same time. The reason for this is because when you know what goes in, what it does, and what comes out? You can build out each section with temporary data until ready to integrate into the main code.
You can see an example of this whole phase here - the empty base functions, logging, etc for the rock, paper, scissors demo.
Step 4: Tying Your Functions Into Main
Once you have your outline, you need to tie them into your main function (the thing that runs when you run your script).
This whole portion is simply to ensure that your logic works.
Does it enter the appropriate function when it's supposed to? If not, why not?
This is where your logging comes into play.
Once you have tied the functions to your main, be sure to run it! You are testing to ensure the flow is accurate.
You can see an example here for the RPS game.
Conclusion
Once you have completed the 4 steps above, you are ready to assign functions to different team members!
Again, there is no one right way to code. This is just the system I have been using that minimizes:
- time spent refactoring code
- fixing new bugs introduced due to lack of planning
- frustration
- ... and more!
Additional Links
Originally linked on LinkedIn, here are the additional links for your convenience.
- Slides were shared here (first "slide" is the recording - just click the right arrow to see the slides)
- The recording was shared here
- The code referenced was shared here
