Groovy 2.5 CliBuilder article (request for feedback)

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

Groovy 2.5 CliBuilder article (request for feedback)

Remko Popma
Hi everyone,

I finished a first draft of an article on Groovy 2.5 CliBuilder

I plan to publish this on DZone and Java Code Geeks when complete.

I'd appreciate your feedback and suggestions for improvement!

Remko
Reply | Threaded
Open this post in threaded view
|

Re: Groovy 2.5 CliBuilder article (request for feedback)

Remko Popma
All, 

I polished the Groovy 2.5 CliBuilder article some more

Feedback (positive or negative) would be great.

On Tue, May 15, 2018 at 11:40 PM, Remko Popma <[hidden email]> wrote:
Hi everyone,

I finished a first draft of an article on Groovy 2.5 CliBuilder

I plan to publish this on DZone and Java Code Geeks when complete.

I'd appreciate your feedback and suggestions for improvement!

Remko

Reply | Threaded
Open this post in threaded view
|

Re: Groovy 2.5 CliBuilder article (request for feedback)

paulk_asert
Looks great!

Two minor points (and they are possibly flaws that also exist in the Groovy doco - I haven't checked):
* I wouldn't use the term "getter methods of an interface", I'd just use "methods of an interface". To avoid confusion with getter methods of JavaBean style classes.
* I would use "annotating properties or setter methods" rather than "annotating fields or setter methods"

Cheers, Paul.


On Tue, May 29, 2018 at 3:03 AM, Remko Popma <[hidden email]> wrote:
All, 

I polished the Groovy 2.5 CliBuilder article some more

Feedback (positive or negative) would be great.

On Tue, May 15, 2018 at 11:40 PM, Remko Popma <[hidden email]> wrote:
Hi everyone,

I finished a first draft of an article on Groovy 2.5 CliBuilder

I plan to publish this on DZone and Java Code Geeks when complete.

I'd appreciate your feedback and suggestions for improvement!

Remko


Reply | Threaded
Open this post in threaded view
|

Re: Groovy 2.5 CliBuilder article (request for feedback)

Jesper Steen Møller
In reply to this post by Remko Popma
Neat article, Remko -- and neat CLI support!

Two very minor nitpicks:

1) The image for 'Script Annotations' is confusingly big/unwieldy, almost to the point of me nearly missing the joke ;-)

2) I'd use // 1, // 2, // 3 for pointing out individual lines in the examples. That way, you can still copy+paste them.

-Jesper

On 28 May 2018, at 19.03, Remko Popma <[hidden email]> wrote:

All, 

I polished the Groovy 2.5 CliBuilder article some more

Feedback (positive or negative) would be great.

On Tue, May 15, 2018 at 11:40 PM, Remko Popma <[hidden email]> wrote:
Hi everyone,

I finished a first draft of an article on Groovy 2.5 CliBuilder

I plan to publish this on DZone and Java Code Geeks when complete.

I'd appreciate your feedback and suggestions for improvement!

Remko


Reply | Threaded
Open this post in threaded view
|

Re: Groovy 2.5 CliBuilder article (request for feedback)

Remko Popma
Jesper,

Thanks, I’ll make the image smaller. 
The numbers in the source code are how AsciiDoc gets rendered on GitHub wiki. It should look like a black circle with a white number inside when rendered as HTML. 

Thanks for checking!

(Shameless plug) Every java main() method deserves http://picocli.info

On May 29, 2018, at 4:17, Jesper Steen Møller <[hidden email]> wrote:

Neat article, Remko -- and neat CLI support!

Two very minor nitpicks:

1) The image for 'Script Annotations' is confusingly big/unwieldy, almost to the point of me nearly missing the joke ;-)

2) I'd use // 1, // 2, // 3 for pointing out individual lines in the examples. That way, you can still copy+paste them.

-Jesper

On 28 May 2018, at 19.03, Remko Popma <[hidden email]> wrote:

All, 

I polished the Groovy 2.5 CliBuilder article some more

Feedback (positive or negative) would be great.

On Tue, May 15, 2018 at 11:40 PM, Remko Popma <[hidden email]> wrote:
Hi everyone,

I finished a first draft of an article on Groovy 2.5 CliBuilder

I plan to publish this on DZone and Java Code Geeks when complete.

I'd appreciate your feedback and suggestions for improvement!

Remko


Reply | Threaded
Open this post in threaded view
|

Re: Groovy 2.5 CliBuilder article (request for feedback)

Remko Popma
In reply to this post by paulk_asert
Paul,

I’ll change “annotating properties” to “annotating fields”. 

About “getter methods for interfaces” and “setter methods for implementation classes”, I need to think about this some more but the distinction is important. 

The annotations can be a bit “magic” for users who don’t know the details of what happens under the hood. 

Without clear documentation users may try to use the annotations on the “getter” method of an implementation class. 

I’ll try to improve the wording but the analogy with JavaBeans is actually helpful rather than confusing, I think. Why do you think this analogy should be avoided?

Remko

(Shameless plug) Every java main() method deserves http://picocli.info

On May 29, 2018, at 4:11, Paul King <[hidden email]> wrote:

Looks great!

Two minor points (and they are possibly flaws that also exist in the Groovy doco - I haven't checked):
* I wouldn't use the term "getter methods of an interface", I'd just use "methods of an interface". To avoid confusion with getter methods of JavaBean style classes.
* I would use "annotating properties or setter methods" rather than "annotating fields or setter methods"

Cheers, Paul.


On Tue, May 29, 2018 at 3:03 AM, Remko Popma <[hidden email]> wrote:
All, 

I polished the Groovy 2.5 CliBuilder article some more

Feedback (positive or negative) would be great.

On Tue, May 15, 2018 at 11:40 PM, Remko Popma <[hidden email]> wrote:
Hi everyone,

I finished a first draft of an article on Groovy 2.5 CliBuilder

I plan to publish this on DZone and Java Code Geeks when complete.

I'd appreciate your feedback and suggestions for improvement!

Remko


Reply | Threaded
Open this post in threaded view
|

Re: Groovy 2.5 CliBuilder article (request for feedback)

paulk_asert


On Tue, May 29, 2018 at 9:43 AM, Remko Popma <[hidden email]> wrote:
Paul,

I’ll change “annotating properties” to “annotating fields”. 

I was suggesting the other way around. Field-like declarations in Groovy without an explicit visibility modifier are properties. That's what your examples show.
 
About “getter methods for interfaces” and “setter methods for implementation classes”, I need to think about this some more but the distinction is important. 

The annotations can be a bit “magic” for users who don’t know the details of what happens under the hood. 

Without clear documentation users may try to use the annotations on the “getter” method of an implementation class. 

I’ll try to improve the wording but the analogy with JavaBeans is actually helpful rather than confusing, I think. Why do you think this analogy should be avoided?

Other people may have a different understanding but I normally see setters as the term used for methods like setFoo, setBar, setBaz, etc. So that's exactly what we want it to mean for implementation classes. The setters will be there either explicitly or for all non readonly properties which will have automatic setters.

The term "getters" is for methods like getFoo, getBar, getBaz etc. The interfaces you are showing don't have such methods, e.g. help(), users(), remaining(). There aren't setters, just interface methods.

Paul.

 

Remko

(Shameless plug) Every java main() method deserves http://picocli.info

On May 29, 2018, at 4:11, Paul King <[hidden email]> wrote:

Looks great!

Two minor points (and they are possibly flaws that also exist in the Groovy doco - I haven't checked):
* I wouldn't use the term "getter methods of an interface", I'd just use "methods of an interface". To avoid confusion with getter methods of JavaBean style classes.
* I would use "annotating properties or setter methods" rather than "annotating fields or setter methods"

Cheers, Paul.


On Tue, May 29, 2018 at 3:03 AM, Remko Popma <[hidden email]> wrote:
All, 

I polished the Groovy 2.5 CliBuilder article some more

Feedback (positive or negative) would be great.

On Tue, May 15, 2018 at 11:40 PM, Remko Popma <[hidden email]> wrote:
Hi everyone,

I finished a first draft of an article on Groovy 2.5 CliBuilder

I plan to publish this on DZone and Java Code Geeks when complete.

I'd appreciate your feedback and suggestions for improvement!

Remko



Reply | Threaded
Open this post in threaded view
|

Re: Groovy 2.5 CliBuilder article (request for feedback)

Remko Popma
Thanks for the clarification. I’ve made some changes based on your feedback. 

Please let me know if you spot any more. 

Thanks!
Remko

(Shameless plug) Every java main() method deserves http://picocli.info

On May 29, 2018, at 12:25, Paul King <[hidden email]> wrote:



On Tue, May 29, 2018 at 9:43 AM, Remko Popma <[hidden email]> wrote:
Paul,

I’ll change “annotating properties” to “annotating fields”. 

I was suggesting the other way around. Field-like declarations in Groovy without an explicit visibility modifier are properties. That's what your examples show.
 
About “getter methods for interfaces” and “setter methods for implementation classes”, I need to think about this some more but the distinction is important. 

The annotations can be a bit “magic” for users who don’t know the details of what happens under the hood. 

Without clear documentation users may try to use the annotations on the “getter” method of an implementation class. 

I’ll try to improve the wording but the analogy with JavaBeans is actually helpful rather than confusing, I think. Why do you think this analogy should be avoided?

Other people may have a different understanding but I normally see setters as the term used for methods like setFoo, setBar, setBaz, etc. So that's exactly what we want it to mean for implementation classes. The setters will be there either explicitly or for all non readonly properties which will have automatic setters.

The term "getters" is for methods like getFoo, getBar, getBaz etc. The interfaces you are showing don't have such methods, e.g. help(), users(), remaining(). There aren't setters, just interface methods.

Paul.

 

Remko

(Shameless plug) Every java main() method deserves http://picocli.info

On May 29, 2018, at 4:11, Paul King <[hidden email]> wrote:

Looks great!

Two minor points (and they are possibly flaws that also exist in the Groovy doco - I haven't checked):
* I wouldn't use the term "getter methods of an interface", I'd just use "methods of an interface". To avoid confusion with getter methods of JavaBean style classes.
* I would use "annotating properties or setter methods" rather than "annotating fields or setter methods"

Cheers, Paul.


On Tue, May 29, 2018 at 3:03 AM, Remko Popma <[hidden email]> wrote:
All, 

I polished the Groovy 2.5 CliBuilder article some more

Feedback (positive or negative) would be great.

On Tue, May 15, 2018 at 11:40 PM, Remko Popma <[hidden email]> wrote:
Hi everyone,

I finished a first draft of an article on Groovy 2.5 CliBuilder

I plan to publish this on DZone and Java Code Geeks when complete.

I'd appreciate your feedback and suggestions for improvement!

Remko



Reply | Threaded
Open this post in threaded view
|

Re: Groovy 2.5 CliBuilder article (request for feedback)

paulk_asert
LGTM!

On Tue, May 29, 2018 at 2:17 PM, Remko Popma <[hidden email]> wrote:
Thanks for the clarification. I’ve made some changes based on your feedback. 

Please let me know if you spot any more. 

Thanks!
Remko

(Shameless plug) Every java main() method deserves http://picocli.info

On May 29, 2018, at 12:25, Paul King <[hidden email]> wrote:



On Tue, May 29, 2018 at 9:43 AM, Remko Popma <[hidden email]> wrote:
Paul,

I’ll change “annotating properties” to “annotating fields”. 

I was suggesting the other way around. Field-like declarations in Groovy without an explicit visibility modifier are properties. That's what your examples show.
 
About “getter methods for interfaces” and “setter methods for implementation classes”, I need to think about this some more but the distinction is important. 

The annotations can be a bit “magic” for users who don’t know the details of what happens under the hood. 

Without clear documentation users may try to use the annotations on the “getter” method of an implementation class. 

I’ll try to improve the wording but the analogy with JavaBeans is actually helpful rather than confusing, I think. Why do you think this analogy should be avoided?

Other people may have a different understanding but I normally see setters as the term used for methods like setFoo, setBar, setBaz, etc. So that's exactly what we want it to mean for implementation classes. The setters will be there either explicitly or for all non readonly properties which will have automatic setters.

The term "getters" is for methods like getFoo, getBar, getBaz etc. The interfaces you are showing don't have such methods, e.g. help(), users(), remaining(). There aren't setters, just interface methods.

Paul.

 

Remko

(Shameless plug) Every java main() method deserves http://picocli.info

On May 29, 2018, at 4:11, Paul King <[hidden email]> wrote:

Looks great!

Two minor points (and they are possibly flaws that also exist in the Groovy doco - I haven't checked):
* I wouldn't use the term "getter methods of an interface", I'd just use "methods of an interface". To avoid confusion with getter methods of JavaBean style classes.
* I would use "annotating properties or setter methods" rather than "annotating fields or setter methods"

Cheers, Paul.


On Tue, May 29, 2018 at 3:03 AM, Remko Popma <[hidden email]> wrote:
All, 

I polished the Groovy 2.5 CliBuilder article some more

Feedback (positive or negative) would be great.

On Tue, May 15, 2018 at 11:40 PM, Remko Popma <[hidden email]> wrote:
Hi everyone,

I finished a first draft of an article on Groovy 2.5 CliBuilder

I plan to publish this on DZone and Java Code Geeks when complete.

I'd appreciate your feedback and suggestions for improvement!

Remko




Reply | Threaded
Open this post in threaded view
|

Re: Groovy 2.5 CliBuilder article (request for feedback)

Remko Popma
Cool!
Thanks again!

Remko

On May 29, 2018, at 14:26, Paul King <[hidden email]> wrote:

LGTM!

On Tue, May 29, 2018 at 2:17 PM, Remko Popma <[hidden email]> wrote:
Thanks for the clarification. I’ve made some changes based on your feedback. 

Please let me know if you spot any more. 

Thanks!
Remko

(Shameless plug) Every java main() method deserves http://picocli.info

On May 29, 2018, at 12:25, Paul King <[hidden email]> wrote:



On Tue, May 29, 2018 at 9:43 AM, Remko Popma <[hidden email]> wrote:
Paul,

I’ll change “annotating properties” to “annotating fields”. 

I was suggesting the other way around. Field-like declarations in Groovy without an explicit visibility modifier are properties. That's what your examples show.
 
About “getter methods for interfaces” and “setter methods for implementation classes”, I need to think about this some more but the distinction is important. 

The annotations can be a bit “magic” for users who don’t know the details of what happens under the hood. 

Without clear documentation users may try to use the annotations on the “getter” method of an implementation class. 

I’ll try to improve the wording but the analogy with JavaBeans is actually helpful rather than confusing, I think. Why do you think this analogy should be avoided?

Other people may have a different understanding but I normally see setters as the term used for methods like setFoo, setBar, setBaz, etc. So that's exactly what we want it to mean for implementation classes. The setters will be there either explicitly or for all non readonly properties which will have automatic setters.

The term "getters" is for methods like getFoo, getBar, getBaz etc. The interfaces you are showing don't have such methods, e.g. help(), users(), remaining(). There aren't setters, just interface methods.

Paul.

 

Remko

(Shameless plug) Every java main() method deserves http://picocli.info

On May 29, 2018, at 4:11, Paul King <[hidden email]> wrote:

Looks great!

Two minor points (and they are possibly flaws that also exist in the Groovy doco - I haven't checked):
* I wouldn't use the term "getter methods of an interface", I'd just use "methods of an interface". To avoid confusion with getter methods of JavaBean style classes.
* I would use "annotating properties or setter methods" rather than "annotating fields or setter methods"

Cheers, Paul.


On Tue, May 29, 2018 at 3:03 AM, Remko Popma <[hidden email]> wrote:
All, 

I polished the Groovy 2.5 CliBuilder article some more

Feedback (positive or negative) would be great.

On Tue, May 15, 2018 at 11:40 PM, Remko Popma <[hidden email]> wrote:
Hi everyone,

I finished a first draft of an article on Groovy 2.5 CliBuilder

I plan to publish this on DZone and Java Code Geeks when complete.

I'd appreciate your feedback and suggestions for improvement!

Remko




12