[Grace-core] Naming (sigh!)

[Andrew P Black]

Kim,

On 19 Apr 2014, at 01:03 , Kim Bruce <kim at cs.pomona.edu> wrote:

> I'm going back heavy duty to rewriting my text, but first I want to make revisions to objectdraw to conform to our latest syntax for classes.  (By the way, the PSU Grace compiler seems to run both graphics and timers fine -- at least so far).
> 
> I only want to make changes to the API once more, so I'm looking for some advice on naming the classes.  I've listed below all of the classes, each followed immediately by its proposed new name.  However, I'm tempted to make a further change to the names for multi-part class names.  I'm tempted to have the second and any further parts start with capital letters.  Thus rather than writing 
> 
> class aDrawable2DAt(location':Location)size(width':Number,height':Number)on(canvas':Canvas)
>                      -> Graphic2DObject
> 
> I'm instead tempted to write:
> 
> class aDrawable2DAt(location':Location)Size(width':Number,height':Number)On(canvas':Canvas)
>                      -> Graphic2DObject
> 
> You will notice that I did that for the color constructor, but not for any of the others.  At the moment, none of the actual methods of any of these classes have multipart names, so there is no consistency issue there.  What do you think?  (... and let me know if you have other suggestions for renaming the classes.
> 
> (If you'd like more documentation on the entire objectdraw library, it can be found at:
> http://www.cs.pomona.edu/~kim/GraceStuff/UsingObjectdrawGrace.pdf
> 
> Kim

For capitalization, I favour a simple rule that's easy to memorize and understand.  The rule that I'm used to is:

	names are in lower case EXCEPT that when words are run together, the initial letter of the subsequent words is upper-cased.
	
	This gives us  if()then()else() and aDrawableAt()size()on() 

Anther, even simpler rule would be

	names are in lower case, EXCEPT that the initial letter of each constituent word is upper-cased.

	This would give us  If()Then()Else and aDrawableAt()Size()On(), which is why we haven't been using that.


What rule are you proposing?

I would not put 2D into any of the names.   Instead, I would call the module Graphics2D.


> Grace class names
> 
> class aColor.r(r')g(g')b(b') -> GColor
> 
> class aColorR(r')G(g')B(b') -> GColor

I think that I would stick with a factory object, since it will have multiple methods

	aColor.rgb(red, green, blue) -> Color

	aColor.hsv(hue, saturation, value) -> Color

	aColor.black -> Color

	aColor.grey(value) -> Color


> class aLocation.at(x':Number,y':Number)->Location
> 
> class aLocationAt(x':Number,y':Number)->Location

I would advocate for a type Vector (or Vector2) that has x and y coordinates, and rich algebra implemented as methods.   I would use Vector to indicate sizes as well as positions.

> 
> class aCanvas.size(width':Number,height':Number) -> Canvas
> 
> class aCanvasSize(width':Number,height':Number) -> Canvas

I'm not sure here if I prefer a factory object or a factory method.  It depends if there is exactly one way to make a Canvas, or more:

	aCanvasWithExtent(extent: Vector) -> Canvas

	aCanvas.withExtent(extent: Vector) -> Canvas

	
> class aGraphicApplication.size(width':Number,height':Number)
>               ->GraphicApplication
> 
> class aGraphicApplicationSize(width':Number,height':Number)
>               ->GraphicApplication
> 

I don't think of the whole application as an object, so that one confuses me.   What does the argument represent?   The size of a canvas that it will create?
Maybe I should just pass the canvas as argument?

	aGraphicApplication.using(aCanvas)
	
	aGraphicApplication.withNewCanvas(extent: Vector)


> 
> class aDrawable.at(location':Location) on (canvas':Canvas) -> GraphicObject
> 
> class aDrawableAt(location':Location) on (canvas':Canvas) -> GraphicObject

This doesn't makes sense to me, since Drawable is presumably abstract.

	aDisk.centeredAt(v: Vector) radius (r: Number) on (canvas : Canvas) -> GraphicObject

	aRectangle.topLeftAt(v: Vector) extent (v: Vector) on (canvas : Canvas) -> GraphicObject

And so on...  Even reading the documentation, I could not tell what the location parameter meant, hence my suggestion to use cneteredAt or topLeftAt, 
or both.
> 
> 
> class aDrawable2D.at(location':Location)size(width':Number,height':Number)on(canvas':Canvas)
>                      -> Graphic2DObject
> 
> class aDrawable2DAt(location':Location)size(width':Number,height':Number)on(canvas':Canvas)
>                      -> Graphic2DObject
> 
> 
> class aResizable2D.at(location':Location)size(width':Number,height':Number)
>                   on(canvas':Canvas)  -> Resizable2DObject
> 
> class aResizable2DAt(location':Location)size(width':Number,height':Number)
>                   on(canvas':Canvas)  -> Resizable2DObject
> 
> 
> class aFramedRect.at(location':Location)size(width':Number,height':Number)
>           on(canvas':Canvas) -> Resizable2DObject
> 
> class aFramedRectAt(location':Location)size(width':Number,height':Number)
>           on(canvas':Canvas) -> Resizable2DObject
> 
> 
> class aFilledRect.at(location':Location)size(width':Number,height':Number)
>           on(canvas':Canvas) -> Resizable2DObject
> 
> class aFilledRectAt(location':Location)size(width':Number,height':Number)
>           on(canvas':Canvas) -> Resizable2DObject

Is filling versus framing a property of the object?  Or is it a property of the way that it is drawn, like its color.
Can I fill a framed rectangle or frame a filled rectangle?    Can I make the fill color of a FilledRectangle transparent?
I'm wondering if there are two kinds of object, or one kind.

> 
> class aFramedOval.at(location':Location)size(width':Number,height':Number)
>           on(canvas':Canvas) -> Resizable2DObject
> 
> class aFramedOvalAt(location':Location)size(width':Number,height':Number)
>           on(canvas':Canvas) -> Resizable2DObject
> 
> 
> class aFilledOval.at(location':Location)size(width':Number,height':Number)
>           on(canvas':Canvas) -> Resizable2DObject
> 
> class aFilledOvalAt(location':Location)size(width':Number,height':Number)
>           on(canvas':Canvas) -> Resizable2DObject
> 
> 
> class aFramedArc.at(location':Location)size(width':Number,height':Number)
>           from(startAngle:Number)to(endAngle:Number)on(canvas':Canvas) -> Resizable2DObject
> 
> class aFramedArcAt(location':Location)size(width':Number,height':Number)
>           from(startAngle:Number)to(endAngle:Number)on(canvas':Canvas) -> Resizable2DObject
> 
> 
> class aFilledArc.at(location':Location)size(width':Number,height':Number)
>           from(startAngle:Number)to(endAngle:Number)on(canvas':Canvas) -> Resizable2DObject
> 
> class aFilledArcAt(location':Location)size(width':Number,height':Number)
>           from(startAngle:Number)to(endAngle:Number)on(canvas':Canvas) -> Resizable2DObject
> 
> 
> class aDrawableImage.at(location':Location)size(width':Number,height':Number)
>           file(fileName:String)on(canvas':Canvas) -> Resizable2DObject
> 
> class aDrawableImageAt(location':Location)size(width':Number,height':Number)
>           file(fileName:String)on(canvas':Canvas) -> Resizable2DObject

	anImage.topLeftAt:(v: Vector) extent (e: Vector) fromFile(fileName:String) on (c:Canvas) 
	anImage.topLeftAt:(v: Vector) sized (fraction: Number) fromFile(fileName:String) on (c:Canvas) 
> 
> 
> class aLine.from(start':Location)to(end':Location)on(canvas':Canvas)
>          -> LinearObject

	aLine.segmentFrom(start:Vector)to(end:Vector)on(c:Canvas)
	
	aLine.withEquation(a:Number)xPlus(b:Number)yIs(canvas:Number)on(canvas:Canvas)

	aLine.through(start:Vector)and(end:Vector)on(c:Canvas)
> 
> class aLineFrom(start':Location)to(end':Location)on(canvas':Canvas)
>          -> LinearObject
> 
> 
> class aText.at(location':Location)with(contents':String)on(canvas':Canvas) 
>                         -> Textual
> 
> class aTextAt(location':Location)with(contents':String)on(canvas':Canvas) 
>                         -> Textual
> 

The best way to answer these questions is often to write the Unit Tests that use the methods and look at the code.

I could not figure out from the documentation what the canvas was for.  Does it make sense to have multiple canvases?  Does it make sense to move drawable objects from one canvas to another?   Can canvases be resized?   I'm wondering if we need canvases at all in the very early programs.

	Andrew