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.
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)
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
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
# 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)
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.
I've been granted API Developer access to SNTCI created an api for "csapi Inventory POE API" and "Hello API" within apiconsole.cisco.comUsing both postman and Powershell with the Invoke-RestMethod command I am able to successfully request a client authent...
Hi, I tried to connect to OpenVul Api by product. I always get a 'PRODUCT NOT FOUND' when I query eg. Cisco Catalyst 3850 series switches or Cisco Catalyst 3850 series . I also tried without %20 but using blank space and same result.Below is the samp...
I fetched a list of devices and pass this into a subsequent getPhone request, with some logic to grab the phone name and speed dial info. My loop may be defective as i'm only getting the last item.here's a snippet of the code: 'for device in dictOfNa...