Current software documentation practices don’t adequately serve developers.
The ultimate goal of software documentation is to help developers find and fix code quickly and efficiently. Still, in most cases, code comments are difficult to understand, incomplete, out of date and untrustworthy to many developers, often resulting in significant additional work and unintended business risks.
Traditionally, supplying detailed documentation and comments in code can help developers quickly get the context surrounding the code they are working on, resulting in increased productivity. While documentation and comments are an important part of software engineering, poor or insufficient documentation is a widespread problem that can ultimately create more problems for developers and negatively impact the business.
Finding the specific code to change requires developers to understand all of the code that might be involved — and actively exclude code that may not be involved — a process that historically has been aided by comments and documentation, albeit poorly. Incorrect documentation results in time and money lost. Transitioning away from relying on developers to add and update comments in code and related documentation requires new methods and tools.
New artificial intelligence technology can exponentially improve software development productivity by guiding new developers to identify behavior (like a bug) and the exact place in the code where changes are needed. Advanced AI tools read and understand source code much like human developers, helping to eliminate the need for comments in code and software documentation. Leveraging AI to identify the code that needs to be updated allows companies to focus developers on what can bring the most value, changing the correct code the first time, whether to fix problems or enhance the software’s capabilities, delivering greater benefits to the business and its clients.
Let’s face it — documenting code can be difficult
Documenting code is one of the most difficult tasks technical staff face. Several factors contribute to the inherent challenges in detailed code documentation. For one, code itself is largely nonlinear. A developer can’t simply start from the top and proceed to the bottom because when they’re given a chunk of code to document, that code’s execution order often isn’t apparent.
Code documentation can also be tricky because writers may not know the technical capacity of their audience. Technical levels of developers vary greatly, and, as such, those in charge of documentation often end up overwriting for the advanced developers by explaining the obvious or alienating less-experienced developers by assuming too much. A developer might also only think to update content they worked on, rather than legacy comments written by someone else who has since left the company, which could also be affected by the changes in the code base. Plus, there’s no guarantee that they have domain expertise in all of the areas of the code that are affected by changes they have implemented — and now they have to add comments. Further, sometimes developers think they know the product so well that it can be difficult to translate that knowledge into practical comments throughout the code. All of these challenges frequently result in lost time and money for a business, whether immediately or at some undetermined time in the future.
As the code base changes and evolves, keeping documentation and comments up to date is a constant challenge for developers. Changes in one area of the code can sometimes inadvertently change the behavior of code elsewhere without recognition by the developer.
Stale comments can be as useless as no documentation because developers don’t know which parts they can rely on. There is often no easy way to determine that comments are correct, which can lead to misinterpretation. Of course, reliable comments depend on facts rather than opinions, but when developers rely on memory alone while making updates after the code changes, the result is often erroneous comments. Even worse, a developer could rely on the documentation and code comments thinking they’re updated when they aren’t.
Finally, comments too often address the what and how — a repeat of the code — not the why. In such a scenario, a developer might opt for a quick fix but fail to update comments along the execution path, leading to inaccurate documentation and trouble down the line.
To combat these challenges, tools utilizing a novel approach to AI decimate the need for documentation. By identifying all of the behaviors in the code upfront, AI-powered tools enable the developer to just describe the behavior of the code before returning with the matching code and necessary data in execution order. This unique AI approach unlocks and activates software’s encoded knowledge from millions of lines of code, unravels spaghetti code and decodes business knowledge so even developers new to an application can be competent and productive from day one. The AI-driven solutions utilize symbolic machine learning on application source code to reduce the need for comprehensive human understanding of code that may not even be relevant. Developers collaborate with AI tools as if they were expert colleagues.
AI keeps up with quick code changes
When a developer who wrote millions of lines of code retires or transitions to a new job and is not replaced right away, the software will undoubtedly progress in their absence, causing organizations to struggle to understand the systems they use and support every day. When a new developer comes on board, they spend entirely too much time trying to understand the previous developers’ intent and finding the exact source code in the code base that requires changing.
Since getting systems to work is always more important than documenting code changes in comments, updating all relevant comments takes a back seat when changes occur frequently. An AI development productivity platform tackles this challenge with intelligence augmentation. The tool has already analyzed, observed and found the relationship between every piece of logic — before the developer has even opened it. From there, the developer provides criteria and iterates with the AI to return the code. Millions of lines of code are quickly reduced to the relevant business behavior so the developer can easily understand that behavior and implement their change.
Leveraging intelligence augmentation, AI tools seamlessly guide the user, distilling the sought-after behavior as code into a single, perfectly organized, comprehensible (cyclomatic complexity of 1), simulated execution of that code. Even better, the real-time code collaboration enabled by such tools allows the developer to keep up with constant changes being made by other developers in the same code base.
With the power of AI, any developer who knows the programming language can fix a bug in 100 lines of code — as long as it’s the right 100 lines. The human guides the development process with their deep knowledge of the business domain while the cognitive agent uses its complete understanding of the source code and original developer intent to assist by answering queries and collaboratively locating the code, thereby simplifying and expediting the developer solving problems.
Precise from every angle, AI tools know the dependency of every line of code on every other line of code. The result is that these advanced tools know the boundaries of every possible value and all the logic in between. AI-powered solutions inherently know every possible outcome of any data input with no file or database, no runtime, just source code. These tools isolate behaviors, predictably, with significantly less thought.
Undoubtedly, new AI-driven tools are dramatically improving software development productivity. The right combination of human-centric principles and cognitive-computing technologies can guide developers at all levels toward the exact place in the code where changes are needed, without documentation or comments in code. As a result, developers can focus on creating applications, identifying code behaviors that need to be updated and making code changes more quickly and efficiently.
About the Author
Steve Brothers is President at Phase Change Software. Steve joined Phase Change Software as the COO in 2018, bringing over 30 years of experience in technology-related organizations with leadership, technical and sales roles in industries such as financial services, healthcare and software development tools. Previously, Steve held positions as CEO at Ajubeo and Executive Vice President and CIO for Urban Lending Solutions. Steve graduated from the University of Colorado at Boulder and holds a B.A. in Philosophy and a B.S. in Information Systems. Steve is a proud husband, father of two boys and a grandson. He is also a mentor at Galvanize and he resides in Golden, CO
Featured image: ©Peshkov
