Level Up: GenAI Supercharges Python
In the intricate tapestry of the programming world, a shining beacon has emerged to save the very fabric of the written software code and the death of programmers from boredom.
It is not what you think. It is not general intelligent AI taking over my job, nor is it a unicorn AI dashboard powered by LLM with a big red button that magically writes bug-free code.
For Python aficionados, it isn’t just another tool. It’s a powerful instrument that can transform the way you work. Imagine stepping into a realm where you’re endowed with the capability to draft inline documentation for your Python (or Java or Swift) code automatically. I employ this method not for a mere handful of functions but for an impressive array of 140+ distinct Python functions in the Data Augmentation with Python book.
The allure doesn’t stop there. While many might assume such an endeavor to be laden with complexity, the truth is that the journey with GenAI is imbued with simplicity and interspersed with flash-of-insight moments that make writing code documentation joyous and surprisingly simple.
Is that laying down too thick? Onward, I am on the roll. :-)
To paint a vivid picture of the significance of inline code documentation for those outside the coding realm, consider this: For a diligent programmer, having precise and comprehensive code documentation is analogous to a hard-pressed Project Manager discovering an unexpected gift of two extra weeks in an already packed schedule or a feeling of euphoric moment when a digital designer clinches the much-coveted Webby award after hours of meticulous crafting of the UI.
For the visionary leader and executive, it is akin to the feeling CFOs get when they uncover a hidden mystical spreadsheet function that maximizes financial outcomes or, like CEOs, discover a magical wand that can increase revenues and keep them well-informed with the pulse of trending social media phenomena.
Using imagery to explain using GenAI to document your code was fun, but the goal is more practical than the lofty image.
By sharing my experiences, the goal is to give you the tools to code smarter, code faster, earn more money, and uncover the untapped intellectual property (IP) within your code.
On to the Welcome screen.
Welcome
Welcome new friends and fellow readers to the latest article in the Demystified AI series. In this article, I revisit our programming roots and explore the impact of these AI-powered tools on the code documentation process. As programmers, we are trained to write documentation for our code, but it can be tedious. However, the recent advancements in GenAI have brought us breakthrough tools like Copilot, Cody, CodeWhiper, and many options that have made coding and code documentation less effort (not effortless) and more efficient.
Fun fact: The Stable Diffusion XL model (Leonardo AI) creates the cover image for this article by gracefully blending technology and artistry. Like the master, he paints the cover photo with art and intellect coalesce in a subtle, divine dance. Some may say she is too perfect and her smile is too genuine, but that’s just Genai’s touch. A hidden gem in the cover photo stems from the title “GenAI Supercharges Python.” A python emblem artistly tattooed below her neck.
However, this version of Leonardo made the mistake of thinking of Python as a giant snake. Guido van Rossum named his language creation after the British TV show The Monty Python Flying Circus.
I wonder what GenAI is thinking while waiting for me to write the next sentence. Perhaps he dreams of the old and zany British TV show, not with old photos or videos but with original images that no human has seen until now, just like the one shown in Figure 1.
In keeping with the Monty Python style, the following is a shameless self-promotion.
Ditch the hoodies and sweaters for holiday gifts! The "Data Augmentation with Python" book is the fashion swag for the brains your friends and employees really want! ??
After that brief and jocose digression, we return to our main topic, using GenAI to write inline documentation for Python code. In particular, this article will cover the following:
As an AI solution architect, I have questioned the need for documented code as a project requirement. Despite my vocal advocacy for the past few months, I am puzzled why GenAI has not been utilized as an assistant rather than a replacement. To better understand the challenge, it’s crucial to define the size, scope, and purpose from the start.
The Challenge
First, it is boring and introspective work.
Crafting code can be a thrilling adventure akin to creating a digital masterpiece. Yet, like any art form, it has its less glamorous moments, and writing documentation often tops that list. For many, documenting code feels monotonous, pushing them to ask, “Why pen down what I’ve just brilliantly coded?”
The parallels between coders and actors are curious, especially when revisiting their work. As many actors often express an aversion to watching their movies, finding it awkward or overly self-critical, developers too can find writing documentation for their code a similar experience. In both instances, it’s a dive into introspection. For actors, it’s re-living their performances; for developers, it’s articulating the logic they’ve intricately woven. It can feel tedious and sometimes even vulnerable as they lay bare their creative processes.
Second, we pay you to do it, so do it. Surprisingly, you do not pay us to document our code.
Step into the shoes of a Project Manager (PM). They have a magnifying glass on development teams, often gauging performance using tools like Jira. A standard metric is “velocity,” which examines how swiftly tasks are completed. It’s a numerical dance, illustrating the ebb and flow of a team’s productivity. And while it provides invaluable insights, it’s focused more on the “how fast” than the “how well.”
On the other end of the spectrum, we have the vigilant Quality Assurance (QA) teams. Their mission is to spot the anomalies, the quirks, and the bugs. Their tools are regression use cases, and their aim is correctness. They are the guardians, ensuring that our digital solutions behave as intended.
Yet, amidst these various measures, one vital aspect is often unnoticed, unrewarded, and unpaid. It is the code documentation. Despite its significance in making code understandable and maintainable, there isn’t a direct metric or incentive for it. It’s like the unsung background score of a movie, vital but often overlooked. Documentation ensures that today’s innovation doesn’t become tomorrow’s enigma. And perhaps it’s high time this silent hero gets its due recognition in the vast software development arena.
Figure 2 illustrates the challenges of writing code documentation. However, my trusted GenAI assistant may have taken a slight liberty in physically representing me. I think the photos share a remarkable likeness, especially the six-pack abs. :-)
I wanted to share a real-life example with you. I authored a book called Data Augmentation with Python, published in May 2023 by Packt Publishing. To complement each book chapter, I created nine Jupyter Notebooks with over 140 Python functions. Although every method is thoroughly explained in the book, the code in the Notebooks is not annotated.
The publisher Packt has made the Jupyter Notebooks for the book Data Augmentation with Python freely available on GitHub.
The link for the Data Augmentation with Python Notebooks on GitHub is https://github.com/PacktPublishing/Data-Augmentation-with-Python.
I prefer self-documented functions and a fully documented paper as an AI Solution Architect. However, as an author, I draw the line at thoroughly explaining the theory and insight in the Notebook because I want readers to purchase the book.
However, why didn’t I write inline documentation for them? Refer to challenge #1 outlined above, and as Mr. Scott - the Chief Engineer of the starship Enterprise - famously said:
I need more time, Captain.
Long story short, over the weekend, I documented all 140+ Python functions using GenAI and uploaded them to Github, where you can download and view the magnificent inline documentation. The following Solution section explains the process in detail.
The Solution
Embarking on the journey of code documentation for 140+ functions can be daunting, but my experience with GenAI has transformed it into a delightful experience. Initially, I was drawn to the convenience of using Google Codey AI on Jupyter Notebook in Colab. I am impressed by the ease with which Codey assists in documenting the code. Codey is well-integrated and user-friendly, as shown in Figure 3.
In Figure 3, you can refer to the function on the same Notebook by name, e.g. print_aug_ai_word2vec(). It has to be one function at a time. Giving more than one function will confuse Codey.
The output of Codey’s written documentation in Figure 4 is 99% perfect. He included the Args with file type and default value, which is excellent. Even better, my digital assistant, Codey, exceeded my request. Looking at “action” and “model_type,” you’ll notice that their types are displayed, even though they’re not in the code. Codey pulls the parameter values from the library. I manually looked them up from the augmentation library to confirm their correctness.
Codey, like many GenAI tools, can sometimes be whimsical. Now and then, it may go off track or suggest something that seems out of place, i.e., “hallucinate.” However, there’s no need to worry. In such cases, Copilot acts as a safeguard, ensuring that the quality and accuracy of the documentation remain intact. However, using Copilot comes at a cost, i.e., the API token counts. The service charges range from $0.01 to $0.08 per request, based on the number of API tokens used.
In my view of digital assistants, Codey would likely be a free intern with good intentions, while Copilot comes across as a professional consultant or a professor at a cost.
When integrating Copilot with Google Colab Jupyter Notebook, I use the “ChatGPT for Google Colab” plugin from the Chrome Web Store. Copilot uses the OpenAI GPT model, and therefore, ChatGPT is the same as Copilot. It differs only in name. Figure 5 shows the Copilot panel, which you can toggle on by clicking the “Copilot” icon on the code cell.
Furthermore, click on the drop-down list, and you have five handy features for your code, as seen in Figure 6.
I have adopted a standard prompt format to ensure that the two GenAIs are working in harmony and generating consistent output across 140+ functions. This format serves as a guideline for the input that will be provided to the GenAIs, eliminating the possibility of any confusion or misinterpretation. The prompt format is simple and does not require any advanced engineering techniques. The format I use is as follows:
领英推荐
Write detail Python inline documentation with default value for the following function: {your_function_name}
It is essential to highlight that prompt engineering is not a crucial factor. Often, prompt engineering is associated with natural language processing, where you manipulate the input text to suit the desired output. In contrast, text-to-image generation requires some minimal manipulation of the prompt. However, I do not need fancy prompt engineering for what we do in code documentation. I use common sense.
By merging the capabilities of two GenAI tools, I achieved a remarkable 95% accuracy rate in writing code documentation for 140+ functions. But it’s not just about the accuracy alone. As I work on my code documentation on the weekend, I often enjoy coffee or tea with a TV sports show or YouTube music playing in the background. The process is not a mindless task of clicking, copying, and pasting. Reading the informative explanation by GenAI was ironically enjoyable. It made me think I could write that well if I had the patience, the unbound energy, and time from my younger days.
In keeping with the Greek mythology theme, my AI assistant, Leonardo, didn’t depict me as someone who dances to YouTube music channels or stuffs down tacos with one hand while typing with the other and watching games on TV. Instead, he portrayed me as Sisyphus pushing the boulder up the hill with determination, as in Figure 7. The 140+ functions would be a boulder, and the task was like pushing it uphill. The image is pleasing to the eye and metaphorically true, but unfortunately, he is wrong. I don't have a beard. :-)
After discussing the process, it’s time to reveal the awe-inspiring results. It is like unearthing enchanting hidden gems.
The Hidden Gems
Welcome to the world of clean and maintainable code! Inline documentation is your friendly guide, explaining the intricacies and intentions behind the code you analyze. GenAI has exceptionally written 95% of the inline Python code documentation for the book "Data Augmentation with Python." Additionally, Packt Publishing has made the Jupyter Notebooks for all nine book chapters available for free on GitHub.
Good documentation can make all the difference in creating easy code to work with rather than a confusing mess. In the following section, I will highlight some of the best examples of inline code documentation generated by GenAI that effectively explain what the code does and why it works that way. These examples are truly hidden gems that can significantly improve your reading, learning, and coding experience.
I want to begin by discussing Figure 8, which shows the generated inline documentation for the function print_safe_parameters(). Although this method does not have any input arguments or output returns, GenAI is able to read the code and generate proper documentation. Personally, I find the sample table for the Covid-19 dataset to be particularly impressive. It is a 10 out of 10 score.
Next up is the print_aug_word_random() method shown in Figure 9. Despite having only two lines of code, this function is quite powerful in terms of functionality. You might have dismissed it as an insignificant function if you hadn't written the inline documentation. The input argument description is excellent, especially for the "action" parameter, where GenAI reads the RandomWordAug() function from the nlpaug library and displays the four possible values along with complete documentation. You must agree that it is impressive work.
Upon first glance, the inline documentation shown in Figure 10 appears to be standard, but upon closer inspection, it becomes clear that it offers more insight than expected. Firstly, GenAI has correctly identified "fname" as the key column name in the input Pandas dataframe. Secondly, GenAI understands that the frequency measuring unit is hertz (Hz), and the roll_off parameters are measured in decibels (dB).
It is evidence that GenAI is an advanced tool capable of reading code and applying its general intelligence to create comprehensive and accurate documentation. By analyzing the code, GenAI can determine the function of each component, its role in the codebase, and how it interacts with other elements. This method enables it to generate thorough, detailed, and easy-to-understand documentation, even for those unfamiliar with the codebase.
There are many other excellent examples to highlight, but the best one is from the code structure from the book. The book uses a standard object-oriented methodology where there is one class named "Pluto." Thus, when you type help(pluto), as in Figure 11, you can read the entire set of methods and its outstanding GenAI doc. This command displays all functions in one place, making it the holy grail of code documentation.
help(pluto) is the holy grail of code documentation.
As we come to the end of this section and prepare to move on to the next one, the Conclusion, let's take a moment to ask our highly skilled and adept in-house artist and all-around genius, Leonardo GenAI, to craft an image that aptly summarizes the Hidden Gems section. The image continues to follow the Greek Olympian style, which, while fanciful, adds a touch of creativity to the representation. Although it may not be completely literal, it captures the awe-inspiring essence of GenAI's documentation prowess. So, please take a look at the image, Figure 12, and you will be the judge of its artistry and meaning. :-)
We are having too much fun, but it is time to draw a conclusion.
The Conclusion
As we conclude our digital journey, we agree that writing inline documentation has often been as thrilling as watching water boil. It’s the broccoli of coding - good for you, but not the first dish you would grab at an all-you-can-eat buffet.
But fear not, for the food trucks have arrived in the form of GenAI — with tools like the free sous-chef Google Codey and the paid Michelin One-star chef Copilot. These aren’t your garden-variety code slingers. They wield the powerful magic of GenAI to transform the dreary into the delightful. With a flick of their neural network wands, they conjure up Python inline documentation, less cold french fries, and more creme de la creme of documentation.
GenAI stands out as an insightful companion in inline Python documentation, offering more than mere descriptions of code functionality. He delves into the depths of your Python libraries, gleaning wisdom and context that go beyond what’s written. GenAI’s documentation is a narrative rich with insight, illuminating the mechanics and philosophy behind your code.
GenAI provides a comprehensive view of your work by combining contextual knowledge and cross-referencing the vast Python ecosystem. It transforms documentation into a dynamic map that guides readers through the intricacies of your codebase, offering clarity and foresight.
Let us propose a toast to the future, where GenAI takes center stage in documentation, replacing its current role as an afterthought that fails to elicit interest. With GenAI, we can now divert our attention to the excitement of creation, leaving the onerous documentation task to our indefatigable GenAI associates. The prospect of having our GenAI-powered scribe is significantly enticing when it surpasses experienced programmers. Let us raise our glasses (or coffee cups, for the night owls) to the future, where GenAI revolutionizes documentation, making it as important as the creative process.
As with other sections, we requested our GenAI friend, Leonardo.ai, to create an illustration for the conclusion. However, there was a discord between humans and GenAI regarding the outcome. Leonardo produced numerous beautiful images based on Greek mythology, with Apollo being the main character. Although they were poetic and flattering, we needed a more realistic image for the conclusion. After much consideration, we finally agreed on using Figure 13 as the conclusion.
Mount Olympics serves as a symbol of GenAI's remarkable accomplishments in recent years. It is humbling to have Homer Simpson represent me, and it reminds me that despite my efforts to promote GenAI to CEOs and CTOs, I am simply content with the simple pleasures in life, like Homer and his love of donuts.
Lastly, I am looking forward to reading your feedback. As always, I apologize for any unintentional errors. The intentional errors are mine and mine alone. :-)
Have a wonderful day, and I hope you enjoy reading this article as much as I enjoy writing it.
Please give it a “thumbs up, like, or heart.” #AI, #GenAI, #ML, #DucHaba
Book Announcement
Before letting you go, I recently authored a book titled?Data Augmentation with Python?with?Packt Publishing. If interested, you can purchase it on Amazon and share your thoughts on the Amazon book review. It will make me happy as a clam. :-)
On GitHub, you can find the entire collection of Jupyter Notebooks for all nine chapters. You can customize the Notebooks to fit your specific project requirements. Additionally, you can run Python code without installing Python.
Demystify AI Series
<End of Doc>