Some names for things

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Some names for things

Adam Murdoch-2

Hi,

Some quick questions on terminology:

In some places we refer to the 'build script', and other places we refer
to the 'build file'. Which one should we use? I don't have a real
preference, other than we use the same term consistently to refer to
this. I suspect we use 'build file' more often than 'build script' in
documentation, so perhaps 'file' is a reasonable choice.

Similarly, is it a 'settings file' or 'settings script'?

I've added some new events to BuildListener, to represent the main steps
of initialising, configuring and executing the build. These are:
settingsEvaluated()
projectsEvaluated()
taskGraphPrepared()

I'm not happy with the name taskGraphPrepared(). I've just realised that
I use the terms 'prepare', 'populate' and 'calculate' to refer to this
step. Is 'evaluate' is a better term to use for this step, ie
taskGraphEvaluated()?

Finally, on Settings, we have a bunch of methods with 'descriptor' in
their name. I think 'project' might be a better term here, as 'project'
is the meaning of the thing being referenced, whereas 'descriptor' is
how they are represented. I think this reads better in the settings file:

project('myproject').buildFileName = 'myproject.gradle'

instead of

descriptor('myproject').buildFileName = 'myproject.gradle'


Adam

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: Some names for things

hans_d
Administrator

On Oct 10, 2008, at 12:42 AM, Adam Murdoch wrote:

>
> Hi,
>
> Some quick questions on terminology:
>
> In some places we refer to the 'build script', and other places we  
> refer to the 'build file'. Which one should we use? I don't have a  
> real preference, other than we use the same term consistently to  
> refer to this. I suspect we use 'build file' more often than 'build  
> script' in documentation, so perhaps 'file' is a reasonable choice.

With the -e option we can pass a String as a script without using a  
file. I think build script and build file are not equivalent. For me  
a build file is a file which content is used as a build script. So I  
think we need both terms. Having said this, I can well imagine that  
the documentation is not clean in regard to this definition. Probably  
in most cases we should use build script.

>
> Similarly, is it a 'settings file' or 'settings script'?

see above

>
> I've added some new events to BuildListener, to represent the main  
> steps of initialising, configuring and executing the build. These are:
> settingsEvaluated()
> projectsEvaluated()
> taskGraphPrepared()
>
> I'm not happy with the name taskGraphPrepared(). I've just realised  
> that I use the terms 'prepare', 'populate' and 'calculate' to refer  
> to this step. Is 'evaluate' is a better term to use for this step,  
> ie taskGraphEvaluated()?

For some reason I'm not happy with evaluated. I think it is different  
to projects and settings where the scripts relate more or less 1:1 to  
the domain objects. The task graph is derived from this. I was also  
thinking about taskGraphCreated. But after all I really like  
taskGraphPopulated. It points out the fact that the task graph object  
is always available but might not be populated yet. In fact we might  
throw a TaskGraphNotPopulatedYetException if it is accessed to early.  
Populated is more precise than prepared and calculated.

>
> Finally, on Settings, we have a bunch of methods with 'descriptor'  
> in their name. I think 'project' might be a better term here, as  
> 'project' is the meaning of the thing being referenced, whereas  
> 'descriptor' is how they are represented. I think this reads better  
> in the settings file:
>
> project('myproject').buildFileName = 'myproject.gradle'
>
> instead of
>
> descriptor('myproject').buildFileName = 'myproject.gradle'

Good idea. This points to a problem I don't have a good solution for  
yet. I unhappy with the duplication I have introduced with those  
project descriptors. We have now to tree objects and registries which  
do pretty much the same things. What I want to do is to have what we  
call now ProjectDescriptor as a base class for our project class. But  
Project extends ProjectDescriptor does not look good. Usually you  
create an actual class from a descriptor but you don't extend it.  
Have you an idea for a better name than project descriptor in such a  
scenario.

Another naming issue: There is the alternative of saying the build  
script is executed/evaluated. I prefer the term evaluated as it is  
used this way by the Groovy API and as it points out that the the  
build script is not an imperative program. I'm not sure if we are  
consistent here in the doc.

- Hans

--
Hans Dockter
Gradle Project lead
http://www.gradle.org





---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: Some names for things

hans_d
Administrator

On Oct 10, 2008, at 9:49 AM, Hans Dockter wrote:

<snip>

> Good idea. This points to a problem I don't have a good solution  
> for yet. I unhappy with the duplication I have introduced with  
> those project descriptors. We have now to tree objects and  
> registries which do pretty much the same things.

I mean we have 'two' tree objects ...

Just as a note. I find this pretty fascinating. There is a category  
of mistakes I make only in written english never in my native  
language. This category is the same as friends of mine with dyslexia  
make in their native German tongue. It is about mixing words that  
sound similar, like there/their, to/two, etc ... When you stumble  
about a posting of mine where something sounds funny you might have  
this in mind.

- Hans

--
Hans Dockter
Gradle Project lead
http://www.gradle.org





---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: Some names for things

Adam Murdoch-2
In reply to this post by hans_d


Hans Dockter wrote:

>
> On Oct 10, 2008, at 12:42 AM, Adam Murdoch wrote:
>
>>
>> Hi,
>>
>> Some quick questions on terminology:
>>
>> In some places we refer to the 'build script', and other places we
>> refer to the 'build file'. Which one should we use? I don't have a
>> real preference, other than we use the same term consistently to
>> refer to this. I suspect we use 'build file' more often than 'build
>> script' in documentation, so perhaps 'file' is a reasonable choice.
>
> With the -e option we can pass a String as a script without using a
> file. I think build script and build file are not equivalent. For me a
> build file is a file which content is used as a build script. So I
> think we need both terms. Having said this, I can well imagine that
> the documentation is not clean in regard to this definition. Probably
> in most cases we should use build script.
>

Right. So, use 'build script' when talking about the logical source, and
'build file' when talking about a physical file?

>>
>> Similarly, is it a 'settings file' or 'settings script'?
>
> see above
>
>>
>> I've added some new events to BuildListener, to represent the main
>> steps of initialising, configuring and executing the build. These are:
>> settingsEvaluated()
>> projectsEvaluated()
>> taskGraphPrepared()
>>
>> I'm not happy with the name taskGraphPrepared(). I've just realised
>> that I use the terms 'prepare', 'populate' and 'calculate' to refer
>> to this step. Is 'evaluate' is a better term to use for this step, ie
>> taskGraphEvaluated()?
>
> For some reason I'm not happy with evaluated. I think it is different
> to projects and settings where the scripts relate more or less 1:1 to
> the domain objects. The task graph is derived from this. I was also
> thinking about taskGraphCreated. But after all I really like
> taskGraphPopulated. It points out the fact that the task graph object
> is always available but might not be populated yet. In fact we might
> throw a TaskGraphNotPopulatedYetException if it is accessed to early.

We throw IllegalStateException when the graph has not been populated.

> Populated is more precise than prepared and calculated.
>

Populated is fine with me.

>>
>> Finally, on Settings, we have a bunch of methods with 'descriptor' in
>> their name. I think 'project' might be a better term here, as
>> 'project' is the meaning of the thing being referenced, whereas
>> 'descriptor' is how they are represented. I think this reads better
>> in the settings file:
>>
>> project('myproject').buildFileName = 'myproject.gradle'
>>
>> instead of
>>
>> descriptor('myproject').buildFileName = 'myproject.gradle'
>
> Good idea. This points to a problem I don't have a good solution for
> yet. I unhappy with the duplication I have introduced with those
> project descriptors. We have now to tree objects and registries which
> do pretty much the same things. What I want to do is to have what we
> call now ProjectDescriptor as a base class for our project class. But
> Project extends ProjectDescriptor does not look good. Usually you
> create an actual class from a descriptor but you don't extend it. Have
> you an idea for a better name than project descriptor in such a scenario.
>

I agree that Project is-a ProjectDescriptor feels wrong. But I do think
they have something in common. That is, they both have a name, project
dir and subprojects, which is what the registries need. We could extract
an interface which ProjectInternal (rather than Project) and
DefaultProjectDescriptor extend/implement, which the single combined
registry class would use. The interface could be called ProjectTreeNode
or similar (names really aren't my thing :)

> Another naming issue: There is the alternative of saying the build
> script is executed/evaluated. I prefer the term evaluated as it is
> used this way by the Groovy API and as it points out that the the
> build script is not an imperative program. I'm not sure if we are
> consistent here in the doc.
>

Evaluated is fine with me.


Adam


---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email