[Pharo-project] new template for class empty comments for OB
Hi lukas could you add the following in OB for missing template http://code.google.com/p/pharo/issues/detail?id=4090 templateOn: aStream aStream nextPutAll: theClass name; nextPutAll: ' has not been documented yet. The class comment should describe the purpose of the class, its collaborations and its variables. '. aStream nextPutAll: 'We encourage you to fill up the following template.'; cr;cr. aStream nextPutAll: 'Class intention';cr ; tab. aStream nextPutAll: 'I''m doing the following ...';cr;cr. aStream nextPutAll: 'Class collaborations'; cr;tab. aStream nextPutAll: 'I usually do not work in isolation but with the help of ...'; cr ;cr . aStream nextPutAll: 'Class main API'; cr; tab. aStream nextPutAll: 'My main public API is ...'. aStream nextPutAll: 'My subclasses may want to override such specific hooks ...'; cr. aStream nextPutAll: 'Implementation notes';cr. self templateLabel: 'Instance Variables:' class: theClass variables: theClass instVarNames on: aStream. self templateLabel: 'Class Instance Variables:' class: theClass class variables: theClass class instVarNames on: aStream I did the same for the default browser. Stef
I think it is a pity to show this lengthy boilerplate when looking at a class comment. For the normal browser it might be ok, but in OB with RB loaded I actually like to see the inferenced instance variable types at one glance when no other comment is available. I think this behavior is more useful in most cases (i.e. when trying to understand code). OB already picks up automatically the system defined class comment template if the RB engine is not used. Lukas -- Lukas Renggli www.lukas-renggli.ch
Ok for me this stupid instance variables typed inferred comments is nearly totally unless. It gives the wrong message: a class comment is not something that can be generated automatically. The intention, collaborations and API are human decisions. I will add it to the default browser because this is the only to make people think that comments are not empty or just a stupid list of instance variables that we can get anyway. Stef On Apr 24, 2011, at 10:20 PM, Lukas Renggli wrote:
I think it is a pity to show this lengthy boilerplate when looking at a class comment. For the normal browser it might be ok, but in OB with RB loaded I actually like to see the inferenced instance variable types at one glance when no other comment is available. I think this behavior is more useful in most cases (i.e. when trying to understand code). OB already picks up automatically the system defined class comment template if the RB engine is not used.
Lukas
-- Lukas Renggli www.lukas-renggli.ch
Hi Lukas, But this is not incompatible. The IVs may still be listed, the template can be adjusted for that Alexandre On 24 Apr 2011, at 16:20, Lukas Renggli wrote:
I think it is a pity to show this lengthy boilerplate when looking at a class comment. For the normal browser it might be ok, but in OB with RB loaded I actually like to see the inferenced instance variable types at one glance when no other comment is available. I think this behavior is more useful in most cases (i.e. when trying to understand code). OB already picks up automatically the system defined class comment template if the RB engine is not used.
Lukas
-- Lukas Renggli www.lukas-renggli.ch
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
Hi Alexandre,
But this is not incompatible. The IVs may still be listed, the template can be adjusted for that
Yes, this is true and the proposed change takes the IVs into account. The only problem is that I have to scroll to the bottom in 90% of the cases as the variables are a couple of pages below the template text. 90% of the time I am looking for information and then something like the variable types is at least useful, a two page template is only "useful" the few times I actually write a comment. Lukas -- Lukas Renggli www.lukas-renggli.ch
I see your point. We need to iterate on what a good template can be. In general, I believe a lot can be extracted from unit test execution that can serve as a good basis for documentation: public, private methods, collaboration, ... Alexandre On 25 Apr 2011, at 03:15, Lukas Renggli wrote:
Hi Alexandre,
But this is not incompatible. The IVs may still be listed, the template can be adjusted for that
Yes, this is true and the proposed change takes the IVs into account. The only problem is that I have to scroll to the bottom in 90% of the cases as the variables are a couple of pages below the template text. 90% of the time I am looking for information and then something like the variable types is at least useful, a two page template is only "useful" the few times I actually write a comment.
Lukas
-- Lukas Renggli www.lukas-renggli.ch
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
Hi! I worked on a small prototype to help me write code documentation. As an example, here is a template that is automatically given for MOShape, an abstract class in Mondrian that does not have any class variables. MOShape has just one instance variable, isCached. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 'MOShape is PLEASE FILL MOShape is an abstract class. The following methods needs to be implemented #absoluteBoundsFor: #containsPoint:for: #display:on: #heightFor: #widthFor: Class collaborations MOFilledShape MORoundedRectangleShape MOEvent MOLineShape MOAbstractLineLayout MOHorizontalLineLayout MOShape MOVerticalLineLayout MONode MOMouseEvent MOFormsShape MOImageShape MOEasel MOViewRenderer MOShapeAdaptor MOGraphElement MOFormsBuilder MOBoundedShape MOChildrenShape MONodeShape Testing classes MOViewRendererTest MondrianTest MOFormsBuilderTest MONewFormsBuilderTest Class public API #absoluteBoundsFor: #apply:bounds: #boundsFor: #canHandleChildren #collectAllShapes #computeBoundsFor: #computeExtentFor: #containsPoint:for: #disableCache #display:on: #enableCache #heightFor: #isCached #isChildShape #isFormsShape #isLineShape #isNodeShape #isShape #scaleElement:by: Implementation notes Instance Variables: isCached -- PLEASE FILL Comments written by AlexandreBergel on 25 April 2011 ' -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= I plan to use this template for each class of Mondrian. The template can be easily automatically processed to detect inconsistency. A collaboration class is a class for which I sent to or received a message from. Unit tests are excluded. A public method is a method that is invoked by an instance of a different class. This is very Java specific, I know. We could scope it to an object instead of a class. What is your opinion on this template? Cheers, Alexandre On 25 Apr 2011, at 11:59, Alexandre Bergel wrote:
I see your point. We need to iterate on what a good template can be.
In general, I believe a lot can be extracted from unit test execution that can serve as a good basis for documentation: public, private methods, collaboration, ...
Alexandre
On 25 Apr 2011, at 03:15, Lukas Renggli wrote:
Hi Alexandre,
But this is not incompatible. The IVs may still be listed, the template can be adjusted for that
Yes, this is true and the proposed change takes the IVs into account. The only problem is that I have to scroll to the bottom in 90% of the cases as the variables are a couple of pages below the template text. 90% of the time I am looking for information and then something like the variable types is at least useful, a two page template is only "useful" the few times I actually write a comment.
Lukas
-- Lukas Renggli www.lukas-renggli.ch
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
the problem of automated is that your would like aslo to know the roles of the class during its interaction. But this could be something to start about the collaboration may be you should only show roots when you have root and leaves. stef On Apr 25, 2011, at 10:25 PM, Alexandre Bergel wrote:
Hi!
I worked on a small prototype to help me write code documentation. As an example, here is a template that is automatically given for MOShape, an abstract class in Mondrian that does not have any class variables. MOShape has just one instance variable, isCached.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 'MOShape is PLEASE FILL MOShape is an abstract class. The following methods needs to be implemented #absoluteBoundsFor: #containsPoint:for: #display:on: #heightFor: #widthFor:
Class collaborations MOFilledShape MORoundedRectangleShape MOEvent MOLineShape MOAbstractLineLayout MOHorizontalLineLayout MOShape MOVerticalLineLayout MONode MOMouseEvent MOFormsShape MOImageShape MOEasel MOViewRenderer MOShapeAdaptor MOGraphElement MOFormsBuilder MOBoundedShape MOChildrenShape MONodeShape
Testing classes MOViewRendererTest MondrianTest MOFormsBuilderTest MONewFormsBuilderTest
Class public API #absoluteBoundsFor: #apply:bounds: #boundsFor: #canHandleChildren #collectAllShapes #computeBoundsFor: #computeExtentFor: #containsPoint:for: #disableCache #display:on: #enableCache #heightFor: #isCached #isChildShape #isFormsShape #isLineShape #isNodeShape #isShape #scaleElement:by: Implementation notes
Instance Variables: isCached -- PLEASE FILL
Comments written by AlexandreBergel on 25 April 2011 ' -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
I plan to use this template for each class of Mondrian. The template can be easily automatically processed to detect inconsistency.
A collaboration class is a class for which I sent to or received a message from. Unit tests are excluded. A public method is a method that is invoked by an instance of a different class. This is very Java specific, I know. We could scope it to an object instead of a class.
What is your opinion on this template?
Cheers, Alexandre
On 25 Apr 2011, at 11:59, Alexandre Bergel wrote:
I see your point. We need to iterate on what a good template can be.
In general, I believe a lot can be extracted from unit test execution that can serve as a good basis for documentation: public, private methods, collaboration, ...
Alexandre
On 25 Apr 2011, at 03:15, Lukas Renggli wrote:
Hi Alexandre,
But this is not incompatible. The IVs may still be listed, the template can be adjusted for that
Yes, this is true and the proposed change takes the IVs into account. The only problem is that I have to scroll to the bottom in 90% of the cases as the variables are a couple of pages below the template text. 90% of the time I am looking for information and then something like the variable types is at least useful, a two page template is only "useful" the few times I actually write a comment.
Lukas
-- Lukas Renggli www.lukas-renggli.ch
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
Why not a "Please comment this class. Look at class XXXX for a good example of comment". Replace XXX with a class you like. Laurent On Sun, Apr 24, 2011 at 7:39 PM, Stéphane Ducasse <stephane.ducasse@inria.fr
wrote:
Hi lukas
could you add the following in OB for missing template
http://code.google.com/p/pharo/issues/detail?id=4090
templateOn: aStream aStream nextPutAll: theClass name; nextPutAll: ' has not been documented yet. The class comment should describe the purpose of the class, its collaborations and its variables. '. aStream nextPutAll: 'We encourage you to fill up the following template.'; cr;cr. aStream nextPutAll: 'Class intention';cr ; tab. aStream nextPutAll: 'I''m doing the following ...';cr;cr.
aStream nextPutAll: 'Class collaborations'; cr;tab. aStream nextPutAll: 'I usually do not work in isolation but with the help of ...'; cr ;cr .
aStream nextPutAll: 'Class main API'; cr; tab. aStream nextPutAll: 'My main public API is ...'.
aStream nextPutAll: 'My subclasses may want to override such specific hooks ...'; cr.
aStream nextPutAll: 'Implementation notes';cr.
self templateLabel: 'Instance Variables:' class: theClass variables: theClass instVarNames on: aStream. self templateLabel: 'Class Instance Variables:' class: theClass class variables: theClass class instVarNames on: aStream
I did the same for the default browser.
Stef
participants (4)
-
Alexandre Bergel -
laurent laffont -
Lukas Renggli -
Stéphane Ducasse