Re: What I want to store in my code comments
Posted: May 30, 2008 8:12 AM
Hi all, I'm new here, but decided to sign up after seeing this post. I did a small research project with a friend back in 2005 addressing precisely this topic, and so I'm sharing below our final proposal. We also implemented a proof-of-concept of each feature except the last one. I can pass that and the associated documentation along to anyone if they are interested. I can be contacted at trickyt *gmail.com
C3 Code Commenting
Final Submission Proposal
Our final submission will include a Visual Studio solution and a technical document describing the project, its challenges, its final state, and possible future expansions. The Visual Studio solution will contain projects concerning the following areas:
This is the core of the system, which consists of interfaces that represent the “model” of the commenting system. It is a library and is meant to be used by other parts of the project.
•Visual Studio Add-in.
The Visual Studio add-in provides integration between the C3 concept of a project (which is a directory of comment-annotated files) and a Visual Studio project. It will allow the user to perform common operations, such as importing and exporting comments.
This system is used to translate ASCII files with comments into the metadata that is used inside the C3 Engine. Export involves taking comment metadata and generating a user view- and edit-able document while importing involves parsing the former into metadata again.
A powerful concept involving metadata comments is one that requires comments to have certain attributes. For example, a business may require all its programmers to annotate their comments with an “Author” field; the validation layer is used to implement business logic embodying this and other requirements.
•Web-based project display.
Similarly to the Visual Studio add-in, the web-based display is an implementation of a view into the C3 Engine model. It will be implemented in ASP.NET and allow the user to browse C3-annotated source files, optionally display different forms of comments, etc.
•Integration of an external feature.
Other forms of business logic may exist in the context of source code management. For example, almost every software company has some form of a bug-tracking system. Often these systems are separate and isolated from the code. We will provide a simple demonstration of how such an external system or database could be tied to the C3 system.