1MEIC07T4: EasyComment - FEUP-MEIC-DS-2024-25/ai4sd GitHub Wiki
EasyComment is an AI-powered tool to automatically generate comments for code.
In a rapidly changing world where software keeps getting more and more complex, it’s necessary to increase the efficiency and the pace at which developers work while still having a clear and understandable documentation of code. That’s what our tool, AI Assistant for Automatic Comment Generation, or for short, EasyComment, was created for. To enable developers to focus on the actual code and let EasyComment deal with documentation. Our tool will read the code, understand it and based on it, generate concise comments for functions, methods, tests, among others.
EasyComment will be flexible/adaptable, allowing users to implement this tool in various programming and markup languages, such as Python and HTML.The integration of EasyComment will be implemented through a Visual Studio Code Extension, allowing users to generate automatic comments for their code directly within the editor environment, contributing for a easier use and acessibility for developers, coders and users, improving work efficiency.
Users will be able to modify the settings of the AI Assistant, according to their needs, such as the technical depth of the comment, the language in which the comments are generated, which functions should or should not be analysed, and so on.
In our vision, this AI Assistant will change how developers and coders will do their documentation, saving time, reducing errors and ambiguity and ultimately leading to a facilitated documentation process.
To develop EasyComment, we researched already existing AI-based tools similar to the one we will develop. The following tools are:
Docify is an automated code comment generator and documentation tool. It enables users to choose the format of the comments, the detail they have or the language they are written in and is able to comment a single function or complete files at a time. At the current time, it doesn't seems to be working, most likely because their security certificate expired.
Akvelon also developed an Auto Comment AI-powered Extension that is able to automatically generate comment for selected snippets of code although not as customizable or powerful as Docify.
A all-rounder AI assistant that does a bit of evrything, including adding documentation/comments to the written code. Something similar to the ChatGPT/Gemini, but it's a extension to the Visual Studio Code. Currently, although it is working, it might raise security issues as it's originated from China with different regulations regarding data privacy and information usage, which may not align with European data protection standards.
Several other similar tools also exist, such as Docly, which is limited to Python, as well Auto-Comment extension in the VSCode. Aside from these, there are various lesser-known tools developed by individuals rather than companies.
Most of these are integrated into IDEs, with Visual Studio Code (VSCode) being the most prominent.
-
EasyComment: This is the central AI component responsible for orchestrating the code analysis, comment generation, and interaction with VSCode.
-
CodeAnalyzer (AI Component): Uses AI techniques to understand the structure and semantics of the code (Python, HTML, etc.).
-
CommentGenerator (AI Component): The AI responsible for producing the relevant comments for code elements based on analysis.
-
VSCodeExtension: Integrates EasyComment with the Visual Studio Code environment, allowing interaction with the code editor, capturing user input, and displaying outputs.
-
SettingsManager: Manages user-customizable settings, such as comment depth, language, and functions to analyze.
-
User : Represents the person who interacts with EasyComment through the VSCode Extension interface. The user starts the code analysis and comment generation and can configure settings, such as comment depth or language preferences.
-
VsCode Extension (FrontEnd) : Facilitates user interaction, enabling features like calling the comment generation process and displaying generated comments directly within the editor. Captures user inputs and sends requests to the backend components for code analysis and comment generation.
-
EasyComment AI : Not really a AI by itself, it's a junction of the Gemini AI API and our functions.
-
Code Analyzer : This component parses and interprets the structure of the user's code. Recognizes functions, methods, classes, and other elements that require documentation.
-
Comment Generator: Suggests and writes meaningful comments, created by the Gemini AI, based on the analysis provided by the CodeAnalyzer. Takes into account settings like comment depth and preferred language to customize output.
-
Gemini AI : The AI which reads the parsed code, given by the Code Analyzer, and gives the outputted comments.
Dont forget about envision in the future, in case they are different. Identify main risks and justify the most important choices to show the soundness of the architecture and design that you have implemented or plan to implement.
- For now TypeScript, RAG Gemini, VS Code API Identify the main technologies, languages and frameworks used. Clearly identify which ones were restrictions imposed by the client and which were your own choices. Justify your choices and explain in your own words the motivation for the restrictions of your client.
When pressing the button of our prototype (with a file selected), if it's the first time running, it will ask for a natural language which the comments they wish to be, and then our backend will process the request and send back with the documentation of all functions
Document any APIs, formats and protocols needed for development (but don't forget that public APIs should also be accessible from the "How to use" above).
Describe coding conventions and other guidelines adopted by the team(s).
Multiple features were added including:
- VSCode extensions was developed and integrated.
- The extension reads the entire file and generates comments for all the functions.
- The extension directly writes comments into the file.
- Comment suggestions shown before applying them, so the user can decide if they want it or not.
- Selection of idiom of the generated comments.
- Scalable and modular server architecture that can be executed in Docker containers and deployed to cloud environments
What went well?
The teams communication and collaboration alongside incremental coding that ensured clear and quality code.
What went wrong?
Leaving certain tasks for the last minute due to busy schedules was sometimes an issue.
What can we do to improve?
In the next sprint more planned features will be implemented in order to maximize the potential of our extension. So far no major problems were found.
DSLE.Sprint.2.-.Made.with.Clipchamp.mp4
Accomplishments:
- Successfully pushed backend code to the merged server.
- Introduced function-level documentation, improving clarity and accessibility (instead of just whole file documentation instantly).
- Extended support to languages similar to C, including C++ and C#.
- Enabled users to host their own LLMs using the OpenAI API.
- Improved overall documentation for the project.
What went well:
All planned tasks for the sprint were successfully completed, and key milestones were achieved.
What didn't go as planned:
Integration with other projects created several challenges, leading to confusion and some doubts during the process.
What can we do to improve:
Ensure smoother integration with external projects by refining processes and communication. Prioritize resolving any bugs or issues with the extension to enhance stability. Improve clarity in coordination and setup for smoother handoffs during integration.
Accomplishments:
- Integrated the extension on the X-Men so that it can be used by everyone.
- Ability to choose which parts of the code should be documented and which parts shouldn't
- Added the option to generate documentation for Flutter
What went well:
All planned tasks in order to deliver the project with all the desired features were successfully done
What didn't go as planned:
Integration with other projects still created some challenges. This problem was eventually resolved.
What can we do to improve:
We are very satisfied with the developed functionalities for the extension, in the future we could improve it by increasing the number of supported coding languages.
- Data privacy and confidentiality: Sending code to an external API can expose sensitive information. Code may contain confidential data that must be protected from unhautorized access. To mitigate this problem the user will be allowed to choose which code is sent for comment generation. This reduces the exposure of unnecessary data.
Describe which tools are used for quality assurance and link to relevant resources. Namely, provide access to reports for coverage and mutation analysis, static analysis, and other tools that may be used for QA.
Explain how to use your tool from an user standpoint. This can include short videos, screenshots, or API documentation, depending on what makes sense for your particular software and target users. If needed, link to external resources or additional markdown files with further details (please add them to this wiki).
Will be added when the project is closer to completion
Link to the factsheets of each team and of each team-member. For example: