Project Maintainability Status

Project Structure

Evaluation: (E)

Detailed Description: The structure of the Strapi project has proven to be excessively complex and disorganized. The organization of folders and files does not follow a clear logic, making it difficult for contributors to locate and understand the different parts of the system. The presence of excessive branching and nested directories adds an additional layer of complexity, further complicating navigation and code maintenance. For example, the "core" folder contains ambiguous subfolders, such as "email," whose purpose is not immediately clear to those who are not familiar with the codebase. This lack of clarity and cohesion in the project structure may result in prolonged periods of investigation and frustration for the team.

                                              Figure 1: Project Structure.

This caused finding the class responsible for some of the issues to be solved very difficult. The structure is very branched and each of the branches has even more repetitive branched folders. For example, inside this core directory (Figure 1) there is a folder called email. What is this for? It is not clear enough for a developer which has never touched this code. As a matter of fact, if the email folder is opened there is a whole new ramification (maybe a new application) inside.

Improvement Suggestions:

• Simplify the folder structure by grouping related functionalities and eliminating unnecessary directories.
• Explicitly document the purpose and hierarchy of each folder, providing a clear guide for contributors to navigate the code.
• Consolidate similar modules and eliminate redundancies in the project structure, thus simplifying the overall architecture.

Project Documentation

Evaluation: (E)

Detailed Description: The documentation for the Strapi project lacks updates and clarity, becoming a source of frustration and confusion for project contributors. The provided information is outdated and may not accurately reflect the current state of the code. Additionally, the lack of clear contribution guidelines makes it difficult for contributors to participate effectively. Contributors may struggle to understand how to set up the development environment or solve specific problems due to the lack of detailed instructions in the documentation.

Improvement Suggestions:

• Implement a regular documentation review process to ensure its accuracy and continuous updating.
• Create a comprehensive contribution guide that includes step-by-step instructions for setting up the development environment, solving common problems, and proposing improvements to the project.
• Utilize collaborative documentation tools to allow contributors to easily contribute and update documentation as needed.

Code Structure

Evaluation: (C)

Detailed Description: Although the source code of the Strapi project follows best practices overall, there is still room for improvement to increase its readability and maintainability. One area of concern is the presence of implicit variables and excessive comments in the code. Implicit variables can lead to ambiguities and make it difficult to understand the data flow. Excessive comments, on the other hand, can clutter the code and hinder its readability, especially if they are redundant or not up to date.

                                              Figure 2: Code Structure.

This is definitely a messy technical debt stacked over time. This bloats classes indefinitely. Each of the classes the team was eager to explore had at least 2-3 big comments, disrupting the flow of code readability.

As a matter of fact, most of these comments (Figure 2) were redundant, purely a code smell

Improvement Suggestions:

• Avoid the use of implicit variables, opting for explicit declarations that make the code clearer and more understandable.
• Review and refactor excessive comments, ensuring they provide relevant and useful information without impairing code readability.
• Establish clear coding style guidelines and conduct regular code reviews to ensure compliance and consistency throughout the project.

Conclusion

Assessing the maintainability of the Strapi project, it is evident that there are significant areas that need improvement to facilitate contributor collaboration and increase efficiency in adding new features and fixing issues. The project structure, characterized by its complexity and lack of clarity, poses a significant challenge, making code navigation and understanding a daunting task. Furthermore, outdated documentation and the lack of clear contribution guidelines further hinder contributor engagement and effective issue resolution.

However, there are positive points to highlight, such as adherence to coding best practices in much of the source code. Nevertheless, there are still opportunities to improve clarity and readability, especially regarding the use of implicit variables and excessive comments. In summary, by implementing the proposed improvement suggestions, the Strapi project can increase its maintainability, making it more accessible, transparent, and easy to work with for contributors, providing more effective collaboration and a more rewarding development experience for all involved.