Strokes framework naming problem

[JL VT]

Hey there Dmitry!, I'm very excited here watching your refactoring, let's
see if my opinion can help a little.

On Sun, Jul 10, 2011 at 10:59 AM, Dmitry Kazakov <dimula73 at gmail.com> wrote:

>
> Ok, what I don't like about this naming:
>
> 1) I don't like KisDabProcessingStrategy name. Some actions like
> "initialization of the stroke" do not work with "dabs" in Lukas' meaning.
> Btw, what is exact meaning of the term "dab"? :)
>

The concept of dab only applies to brushes that paint a succession of
stamped images to the canvas.
Most photoshop brushes (those that use images) paint 1 copy of their mask at
a time (modified by parameters like color, opacity, etc). They work like a
stamp (the wooden object here
http://www.garetto.cl/images/productos/1932/img1.jpg ) that successively
stamps on the canvas at every instance of PaintAt (producing a result like
this http://cdn.clasipar.com/pictures/photos/001/398/953/vga_sello2.jpg ).
Each one of those seals is a Dab.

Not a very concise definition but I think that is as precise as it goes.


> I want to call it like KisStrokeJobStrategy. What do you think, is it easy
> to distinguish it form KisStrokeJob class?
>

It is easy to distinguish because they are related. KisStrokeJobStrategy
works with instances of KisStrokeJob (if I understood the diagram
correctly), describing how to use them.

I think the name KisStrokeJobStrategy is much better.

Dab is very specific to brushes that work like stamps. New brush engines
like the Sketch Brush do not work with "dabs" anymore; they may use PaintAt,
but they are not stamping seals over the canvas 1 at a time. So I think we
should look for a better name to refer to single operations of painting,
something more general.

Some brainstorming follows:
stroke unit
stroke node
painting iteration
paint instace/instant
stroke instant
slice
stroke differential (as opposed to stroke integral which would be the entire
stroke)
paint differential


> 2) I don't like the fact that the definition of the subtype of the class is
> put into the beginning of the name.
>
> KisPainterBasedStrokeStrategy -- probably, not good
> KisStrokeStrategyPainterBased -- better?
>
> FreehandStrokeStrategy -- not good
> KisStrokeStrategyFreehand -- better?
>
> What do you think? What is the common practice here?
>

I (think I) have seen both practices.
I've seen the Subtype-goes-at-the-end naming strategy in classes like
KoDocumentSection (there's -View, -Delegate and -Model) and for me it was
very easy to follow.

The reason it is easy to follow is because I can simply grep for classes
with the same root and will find all subtypes. That won't work with the
reverse style of naming which is also less logical if you ask me (obviously
I can perform a better regular expression search but... it will be more
contrived).

I think using:

Global Prefix - Type - Subtype - Subsubtype

Is the most logical convention, and useful when looking for related classes.



> 3) I don't know where I should add Kis- prefix and where not. These classes
> are too small, too specific and too private to use such global prefix. What
> is the general rule there?
>

I don't know if there's a general rule. We're following the KDELibs coding
style so I assume we're also trying to follow the naming conventions:
http://techbase.kde.org/Policies/Library_Code_Policy
But I couldn't find anything related to this particular situation.

In my opinion, classes that are not going to be in contact with "the outside
world" during their lifetime should have no Kis- prefix.

So if those classes are too small, too specific and too private, I'd skip
the Kis prefix.


4) Well, and, finally, the word 'strategy' is too long for names =( But I
> can't simply remove it because there are classes like KisStroke and
> KisStrokeJob.
>

Don't worry about class names being too long. Screens are getting larger and
larger, and people who insist on editing their code on a small screen within
a console with 80 characters per column are a minority; the majority will (I
believe) gladly trade off some screen space in exchange for having a better
clue of what the code does.

I was grateful of having a class named KoDocumentSectionDelegate, I didn't
care that it was long and took 25 characters all by itself, its function was
clear and it saved me time; that's what matters in the end.

Keep the word Strategy.


> Thanks for your advices in advance! =)
>
>
May it be useful to you!.

Best regards,
~Pentalis.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.kde.org/pipermail/kimageshop/attachments/20110710/3211d27e/attachment.htm