The Artima Developer Community
Articles | News | Weblogs | Books | Forums
Artima Forums | Articles | Weblogs | Java Answers | News
Sponsored Link •

Weblogs Forum
What I want to store in my code comments

12 replies on 1 page. Most recent reply: Jun 2, 2008 9:50 AM by James Watson

Welcome Guest
  Sign In

Go back to the topic listing  Back to Topic List Click to reply to this topic  Reply to this Topic Click to search messages in this forum  Search Forum Click for a threaded view of the topic  Threaded View   
Previous Topic   Next Topic
Flat View: This topic has 12 replies on 1 page
Christopher Diggins

Posts: 1215
Nickname: cdiggins
Registered: Feb, 2004

What I want to store in my code comments (View in Weblogs)
 		Posted: May 28, 2008 8:03 AM
Reply to this message Reply
Summary
The old school approach to comments was to toss them out during the tokenization phase of compiling. Modern IDEs are making comments increasingly relevant to the software development process. So what happens if we push the idea even further?
Advertisement
I have been talking with some developers about what they want in their next generation IDEs (no I'm not working on something like that, and if I told you about it I'd have to erase your brain). The list is pretty straightforward:
  • Fine grained versioning control at the programming element - let me know who authored or last modified a my function/class, also function level undo
  • Test-driven development support - show/hide the tests, and let me know whether it has been changed since it was last tested
  • Requirements binding - what requirement a feature is connected to
  • Model binding - what component of the model this feature connected to
  • Bug/work-item tracking - what bugs or work-items are associated with this program element
What is interesting is that everything necessary for implementing these features can be placed within comments, if an IDE is intelligent about showing/hiding/managing the relevant information. I'd be interested in hearing what features you'd like that could be easily implemented by inserting metadata within comments?


Brian Slesinsky

Posts: 43
Nickname: skybrian
Registered: Sep, 2003

Re: What I want to store in my code comments Posted: May 28, 2008 1:02 PM
Reply to this message Reply
In Java, you would use annotations for this. Annotations can be thought of as specially formatted comments that are intended for tools.

Mark Thornton

Posts: 275
Nickname: mthornton
Registered: Oct, 2005

Re: What I want to store in my code comments Posted: May 28, 2008 2:33 PM
Reply to this message Reply
I don't see the need for anything to be added to comments to support fine grained version information. The IDE can obtain that detail from the VCS and display it in the margins of anywhere else convenient. The old $$key: ... $$ stuff was necessary when using plain text editors.
The same applies to bug/work item tracking.

For test and model binding I prefer to use special syntax which is distinct from comments. The annotation syntax in Java is an example of this. Using comments is hack when you can't get the language changed.

Finally requirements binding is something that probably does belong in comments, albeit stylised ones similar to JavaDoc entries.

indranil banerjee

Posts: 38
Nickname: indranil
Registered: Nov, 2004

Re: What I want to store in my code comments Posted: May 28, 2008 2:37 PM
Reply to this message Reply
Before java had annotations folks were using javadoc comments to associate metadata with code. xDoclet comes to mind, where javadoc comments were used to generate deployment descriptors for EJBs. It was convenient but, like the rest of J2EE, it was a huge kludge.
Java and .Net now have a builtin mechanism for metadata in the form of annotations/attributes respectively.

.Net attributes are used in the wild for xml serialization of classes; object relational mapping; text representation of enum, amongst many other things.

Built in metadata support that can be checked by the compiler is much more useful than comment kludges which require other tools and extra build steps.

Mark Thornton

Posts: 275
Nickname: mthornton
Registered: Oct, 2005

Re: What I want to store in my code comments Posted: May 28, 2008 2:40 PM
Reply to this message Reply
Slightly off topic, but what I would really like to be able to include in comments are the scribbled diagrams I often create while designing the code. I want to see the diagrams directly in the IDE as diagrams within the code or floating alongside (and not as mere links). Properly formatted and styled comments wouldn't go amiss either.

John Cowan

Posts: 36
Nickname: johnwcowan
Registered: Jul, 2006

Re: What I want to store in my code comments Posted: May 28, 2008 5:33 PM
Reply to this message Reply
Why not put your code in the comments too, while you are at it?

Annotations and pragmas exist for a reason.

Steve Merrick

Posts: 9
Nickname: erisian
Registered: Mar, 2008

Re: What I want to store in my code comments Posted: May 29, 2008 3:03 AM
Reply to this message Reply
"I prefer to use special syntax which is distinct from comments." - Mark Thornton

Yes. There are many features that could be made easier and more intuitive using comments, but let's make them an easily-identifiable special case; something we can easily and quickly distinguish from 'ordinary comments' - both visually *AND* in a search or replace operation.

Greg Wilson

Posts: 6
Nickname: gvwilson
Registered: Oct, 2005

Re: What I want to store in my code comments Posted: May 29, 2008 8:30 AM
Reply to this message Reply
I think the notion that comments have to be ASCII text (formatted or otherwise) is the root of the problem --- everyone else's documents allow rich embedding, so why shouldn't source code? See http://www.cs.toronto.edu/~gvwilson/articles/extprog-acmqueue-2004.pdf for a discussion.

Paul Korney

Posts: 2
Nickname: pkorney
Registered: Mar, 2008

Re: What I want to store in my code comments Posted: May 29, 2008 2:43 PM
Reply to this message Reply
This sounds like D.E. Knuth's "Literate Programming"... or is this a new idea? I certainly would like to see something like this that enforced some conventions for any of these uses of Java comments (e.g. like in eclipse with annotations) while allowing complete flexibility in the editing view and focus (e.g. like eclipse perspectives).

Timothy Bussmann

Posts: 1
Nickname: trickyt
Registered: May, 2008

Re: What I want to store in my code comments Posted: May 30, 2008 5:12 AM
Reply to this message Reply
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:

•Engine.
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.

•Import/Export layer.
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.

•Validation layer.
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.

Christopher Diggins

Posts: 1215
Nickname: cdiggins
Registered: Feb, 2004

Re: What I want to store in my code comments Posted: Jun 1, 2008 12:39 PM
Reply to this message Reply
> Built in metadata support that can be checked by the
> compiler is much more useful than comment kludges which
> require other tools and extra build steps.

I completely agree. What I was calling comments, encompasses attributes and annotations (my apologies for misuse of terminology). So allow me to refer to all metadata as annotations. The following wish list should be more lucid:

* I want all programming languages to support annotations
* I don't want any more ad-hoc comment processing tools
* Unit tests should be stored as annotations (not in separate files) because they have documentation value
* Contracts (e.g. preconditions, postconditions, invariants) should be stored in annotations
* Traditional comments should be annotations

Arun Manivannan

Posts: 1
Nickname: arunodhaya
Registered: Jun, 2008

Re: What I want to store in my code comments Posted: Jun 1, 2008 8:39 PM
Reply to this message Reply
> Slightly off topic, but what I would really like to be
> able to include in comments are the scribbled diagrams I
> often create while designing the code. I want to see the
> diagrams directly in the IDE as diagrams within the code
> or floating alongside (and not as mere links). Properly
> formatted and styled comments wouldn't go amiss either.

Thats a great thing to be in an IDE. Most diagrams are lost in my case with no use to people who see my code some days later (even the code doesnt make much sense without the diagram from my old notepad)

James Watson

Posts: 2024
Nickname: watson
Registered: Sep, 2005

Re: What I want to store in my code comments Posted: Jun 2, 2008 9:50 AM
Reply to this message Reply
> > Built in metadata support that can be checked by the
> > compiler is much more useful than comment kludges which
> > require other tools and extra build steps.
>
> I completely agree. What I was calling comments,
> encompasses attributes and annotations (my apologies for
> misuse of terminology). So allow me to refer to all
> metadata as annotations.

I Java annotations are not only useful to IDEs and similar tools. They can actually be referred to in code to allow for dependency injection and whatever else you might want to do with them. They aren't completely separate from your code.

Personally, I question whether this is really a good thing. It seems unproven and possibly unnecessary. Of course, it might be something that's been done in another language or languages for years and I just don't know about it.

In any event, when you use the term annotations, you may be implying more than you mean to some people. I think metadata is clear enough.

Flat View: This topic has 12 replies on 1 page
Topic: What I want to store in my code comments Previous Topic   Next Topic Topic: JavaOne 2008, Day 2
Sponsored Links


Google
  Web Artima.com   

Copyright © 1996-2019 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use