Hi guys I'm fed up to get methods without comments and without little examples. In FileSystem, I wrote most of the comments and I tried to add an obvious example: basenameWithIndicator "Returns the basename with the indicator appended, i.e. /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo basenameWithIndicator is 'foo/'" ^ self basename , self indicator Now let us look at: withExtension: aString ^ self withPath: (self path withExtension: aString) Nice comment :( I would like to support PythonDoctest (yes we are not the only one to have ideas let us face is dear friends) def multiply(a, b): """ >>> multiply(4, 3) 12 >>> multiply('a', 3) 'aaa' """ return a * b Because we can make sure that the comments are accurate. withExtension: aString "Returns a new file reference with a different file extension" <exp: '/tmp/file.txt' asFileReference withExtension: 'log' value: '/tmp/file.log' asFileReference > ^ self withPath: (self path withExtension: aString) It will help us to have a distinction between printOn: and displayString Typically '/tmp/file.txt' asFileReference withExtension: 'log' printString is bad since it returns File @ '/tmp/file.log' which is not an reexecutable expression So let me know what you think. - tell me that we have already test unit (yes the ones I wrote too) => they do not have the same purpose For me this is getting to be important. Stef
On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo@free.fr> wrote:
Hi guys
I'm fed up to get methods without comments and without little examples. In
+1 ! We can setup a small group of people interested to build examples at ESUG.
FileSystem, I wrote most of the comments and I tried to add an obvious example:
basenameWithIndicator "Returns the basename with the indicator appended, i.e. /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo basenameWithIndicator is 'foo/'"
^ self basename , self indicator
Now let us look at:
withExtension: aString ^ self withPath: (self path withExtension: aString)
Nice comment :(
I would like to support PythonDoctest (yes we are not the only one to have ideas let us face is dear friends)
+1 https://en.wikipedia.org/wiki/Doctest
def multiply(a, b): """ >>> multiply(4, 3) 12 >>> multiply('a', 3) 'aaa' """ return a * b
Because we can make sure that the comments are accurate.
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
It will help us to have a distinction between printOn: and displayString
Typically
'/tmp/file.txt' asFileReference withExtension: 'log'
printString is bad
since it returns File @ '/tmp/file.log' which is not an reexecutable expression
So let me know what you think. - tell me that we have already test unit (yes the ones I wrote too) => they do not have the same purpose
For me this is getting to be important.
Maybe a subset of Pharo could be defined as core with a kind of API freeze, so we can spend some time documenting the corresponding methods and classes. -- Serge Stinckwich UCBN & UMI UMMISCO 209 (IRD/UPMC) Every DSL ends up being Smalltalk http://www.doesnotunderstand.org/
Tx serge - I think that we should agree on the pragma or way to express it. May be we can do the same as in Python and use a comment instead of a pragma. I prefer a pragma because we can query them easily. So any idea instead of <exp: value:> <expression: return: > withExtension: aString "Returns a new file reference with a different file extension" <exp: '/tmp/file.txt' asFileReference withExtension: 'log' value: '/tmp/file.log' asFileReference > ^ self withPath: (self path withExtension: aString) - then incrementally we can start taking on system for example FS and use it. Stef Le 18/8/16 à 11:51, Serge Stinckwich a écrit :
On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo@free.fr> wrote:
Hi guys
I'm fed up to get methods without comments and without little examples. In +1 ! We can setup a small group of people interested to build examples at ESUG.
FileSystem, I wrote most of the comments and I tried to add an obvious example:
basenameWithIndicator "Returns the basename with the indicator appended, i.e. /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo basenameWithIndicator is 'foo/'"
^ self basename , self indicator
Now let us look at:
withExtension: aString ^ self withPath: (self path withExtension: aString)
Nice comment :(
I would like to support PythonDoctest (yes we are not the only one to have ideas let us face is dear friends) +1
https://en.wikipedia.org/wiki/Doctest
def multiply(a, b): """ >>> multiply(4, 3) 12 >>> multiply('a', 3) 'aaa' """ return a * b
Because we can make sure that the comments are accurate.
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
It will help us to have a distinction between printOn: and displayString
Typically
'/tmp/file.txt' asFileReference withExtension: 'log'
printString is bad
since it returns File @ '/tmp/file.log' which is not an reexecutable expression
So let me know what you think. - tell me that we have already test unit (yes the ones I wrote too) => they do not have the same purpose
For me this is getting to be important. Maybe a subset of Pharo could be defined as core with a kind of API freeze, so we can spend some time documenting the corresponding methods and classes.
Hi, I like this problem very much. I think we are not leveraging the objects we have in the image. Tests can help, but they are way too disconnected from the code and they are not really useful for detailed questions. I am also happy that you are considering the use of pragmas for this purpose. As you know, Stefan Reichhart and I worked on the examples engine since a couple of years and I think we now start to have a working solution. Because this would be a significant departure from tests, we first wanted to get a more thorough documentation of the current state before opening the discussion to the community to see how this can fit in Pharo or at least in the ecosystem. I think we will have this ready in a draft form in a couple of days, and it would be great to have a critical discussion about it at ESUG. Cheers, Doru
On Aug 18, 2016, at 1:32 PM, stepharo <stepharo@free.fr> wrote:
Tx serge
- I think that we should agree on the pragma or way to express it. May be we can do the same as in Python and use a comment instead of a pragma. I prefer a pragma because we can query them easily.
So any idea instead of <exp: value:>
<expression: return: >
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
- then incrementally we can start taking on system for example FS and use it.
Stef
Le 18/8/16 à 11:51, Serge Stinckwich a écrit :
On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo@free.fr> wrote:
Hi guys
I'm fed up to get methods without comments and without little examples. In +1 ! We can setup a small group of people interested to build examples at ESUG.
FileSystem, I wrote most of the comments and I tried to add an obvious example:
basenameWithIndicator "Returns the basename with the indicator appended, i.e. /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo basenameWithIndicator is 'foo/'"
^ self basename , self indicator
Now let us look at:
withExtension: aString ^ self withPath: (self path withExtension: aString)
Nice comment :(
I would like to support PythonDoctest (yes we are not the only one to have ideas let us face is dear friends) +1
https://en.wikipedia.org/wiki/Doctest
def multiply(a, b): """ >>> multiply(4, 3) 12 >>> multiply('a', 3) 'aaa' """ return a * b
Because we can make sure that the comments are accurate.
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
It will help us to have a distinction between printOn: and displayString
Typically
'/tmp/file.txt' asFileReference withExtension: 'log'
printString is bad
since it returns File @ '/tmp/file.log' which is not an reexecutable expression
So let me know what you think. - tell me that we have already test unit (yes the ones I wrote too) => they do not have the same purpose
For me this is getting to be important. Maybe a subset of Pharo could be defined as core with a kind of API freeze, so we can spend some time documenting the corresponding methods and classes.
-- www.tudorgirba.com www.feenk.com "Every thing has its own flow."
Hi doru
Hi,
I like this problem very much. I think we are not leveraging the objects we have in the image. Tests can help, but they are way too disconnected from the code and they are not really useful for detailed questions.
I am also happy that you are considering the use of pragmas for this purpose.
As you know, Stefan Reichhart and I worked on the examples engine since a couple of years and I think we now start to have a working solution. I do not want 5 pragmas and dependencies between methods and examples. KISS. Pharo tends to forget KISS far too often recently. You know exactly what I do not want: conceptual (and code) bloat. Because this would be a significant departure from tests, we first wanted to get a more thorough documentation of the current state before opening the discussion to the community to see how this can fit in Pharo or at least in the ecosystem. I think we will have this ready in a draft form in a couple of days, and it would be great to have a critical discussion about it at ESUG. My plate is really full. I have a super long list of things that I want to discuss at ESUG.
Stef
Cheers, Doru
On Aug 18, 2016, at 1:32 PM, stepharo <stepharo@free.fr> wrote:
Tx serge
- I think that we should agree on the pragma or way to express it. May be we can do the same as in Python and use a comment instead of a pragma. I prefer a pragma because we can query them easily.
So any idea instead of <exp: value:>
<expression: return: >
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
- then incrementally we can start taking on system for example FS and use it.
Stef
Le 18/8/16 à 11:51, Serge Stinckwich a écrit :
On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo@free.fr> wrote:
Hi guys
I'm fed up to get methods without comments and without little examples. In +1 ! We can setup a small group of people interested to build examples at ESUG.
FileSystem, I wrote most of the comments and I tried to add an obvious example:
basenameWithIndicator "Returns the basename with the indicator appended, i.e. /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo basenameWithIndicator is 'foo/'"
^ self basename , self indicator
Now let us look at:
withExtension: aString ^ self withPath: (self path withExtension: aString)
Nice comment :(
I would like to support PythonDoctest (yes we are not the only one to have ideas let us face is dear friends) +1
https://en.wikipedia.org/wiki/Doctest
def multiply(a, b): """ >>> multiply(4, 3) 12 >>> multiply('a', 3) 'aaa' """ return a * b
Because we can make sure that the comments are accurate.
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
It will help us to have a distinction between printOn: and displayString
Typically
'/tmp/file.txt' asFileReference withExtension: 'log'
printString is bad
since it returns File @ '/tmp/file.log' which is not an reexecutable expression
So let me know what you think. - tell me that we have already test unit (yes the ones I wrote too) => they do not have the same purpose
For me this is getting to be important. Maybe a subset of Pharo could be defined as core with a kind of API freeze, so we can spend some time documenting the corresponding methods and classes.
-- www.tudorgirba.com www.feenk.com
"Every thing has its own flow."
Hi,
On Aug 18, 2016, at 2:41 PM, stepharo <stepharo@free.fr> wrote:
Hi doru
Hi,
I like this problem very much. I think we are not leveraging the objects we have in the image. Tests can help, but they are way too disconnected from the code and they are not really useful for detailed questions.
I am also happy that you are considering the use of pragmas for this purpose.
As you know, Stefan Reichhart and I worked on the examples engine since a couple of years and I think we now start to have a working solution. I do not want 5 pragmas and dependencies between methods and examples. KISS. Pharo tends to forget KISS far too often recently. You know exactly what I do not want: conceptual (and code) bloat.
It think it is KISS. If you only want one feature, you use exactly one pragma <gtExample>. Nothing else. If you want more, as people do, you can get more. But, I wonât go into a debate now. First, I would like to present what exists and then you can form an opinion if you want. Just a note: there already exists in the image a first implementation of GTExample, and this proved very useful for testing the inspector and spotter. However, this was introduced without proper discussion, and as we do not want to impose anything we will remove the whole 1400 lines of code of the GTExample implementation from the GT-Inspector package as it did not belong there anyway, and we will make the new one available separately outside of Pharo. In this way, people can look at it if they want and we can have a discussion if desired.
Because this would be a significant departure from tests, we first wanted to get a more thorough documentation of the current state before opening the discussion to the community to see how this can fit in Pharo or at least in the ecosystem. I think we will have this ready in a draft form in a couple of days, and it would be great to have a critical discussion about it at ESUG. My plate is really full. I have a super long list of things that I want to discuss at ESUG.
Ok. Doru
Stef
Cheers, Doru
On Aug 18, 2016, at 1:32 PM, stepharo <stepharo@free.fr> wrote:
Tx serge
- I think that we should agree on the pragma or way to express it. May be we can do the same as in Python and use a comment instead of a pragma. I prefer a pragma because we can query them easily.
So any idea instead of <exp: value:>
<expression: return: >
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
- then incrementally we can start taking on system for example FS and use it.
Stef
Le 18/8/16 à 11:51, Serge Stinckwich a écrit :
On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo@free.fr> wrote:
Hi guys
I'm fed up to get methods without comments and without little examples. In +1 ! We can setup a small group of people interested to build examples at ESUG.
FileSystem, I wrote most of the comments and I tried to add an obvious example:
basenameWithIndicator "Returns the basename with the indicator appended, i.e. /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo basenameWithIndicator is 'foo/'"
^ self basename , self indicator
Now let us look at:
withExtension: aString ^ self withPath: (self path withExtension: aString)
Nice comment :(
I would like to support PythonDoctest (yes we are not the only one to have ideas let us face is dear friends) +1
https://en.wikipedia.org/wiki/Doctest
def multiply(a, b): """ >>> multiply(4, 3) 12 >>> multiply('a', 3) 'aaa' """ return a * b
Because we can make sure that the comments are accurate.
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
It will help us to have a distinction between printOn: and displayString
Typically
'/tmp/file.txt' asFileReference withExtension: 'log'
printString is bad
since it returns File @ '/tmp/file.log' which is not an reexecutable expression
So let me know what you think. - tell me that we have already test unit (yes the ones I wrote too) => they do not have the same purpose
For me this is getting to be important. Maybe a subset of Pharo could be defined as core with a kind of API freeze, so we can spend some time documenting the corresponding methods and classes.
-- www.tudorgirba.com www.feenk.com
"Every thing has its own flow."
-- www.tudorgirba.com www.feenk.com "Next time you see your life passing by, say 'hi' and get to know her."
As I already told you and the board, I will just leave if such a solution get pushed into Pharo.
Hi,
I like this problem very much. I think we are not leveraging the objects we have in the image. Tests can help, but they are way too disconnected from the code and they are not really useful for detailed questions.
I am also happy that you are considering the use of pragmas for this purpose.
As you know, Stefan Reichhart and I worked on the examples engine since a couple of years and I think we now start to have a working solution. I do not want 5 pragmas and dependencies between methods and examples. KISS. Pharo tends to forget KISS far too often recently. You know exactly what I do not want: conceptual (and code) bloat. It think it is KISS. If you only want one feature, you use exactly one pragma <gtExample>. Nothing else. If you want more, as people do, you can get more.
But, I wonât go into a debate now. First, I would like to present what exists and then you can form an opinion if you want.
Just a note: there already exists in the image a first implementation of GTExample, and this proved very useful for testing the inspector and spotter. However, this was introduced without proper discussion, and as we do not want to impose anything we will remove the whole 1400 lines of code of the GTExample implementation from the GT-Inspector package as it did not belong there anyway, and we will make the new one available separately outside of Pharo. In this way, people can look at it if they want and we can have a discussion if desired.
Because this would be a significant departure from tests, we first wanted to get a more thorough documentation of the current state before opening the discussion to the community to see how this can fit in Pharo or at least in the ecosystem. I think we will have this ready in a draft form in a couple of days, and it would be great to have a critical discussion about it at ESUG. My plate is really full. I have a super long list of things that I want to discuss at ESUG. Ok.
Doru
Stef
Cheers, Doru
On Aug 18, 2016, at 1:32 PM, stepharo <stepharo@free.fr> wrote:
Tx serge
- I think that we should agree on the pragma or way to express it. May be we can do the same as in Python and use a comment instead of a pragma. I prefer a pragma because we can query them easily.
So any idea instead of <exp: value:>
<expression: return: >
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
- then incrementally we can start taking on system for example FS and use it.
Stef
Le 18/8/16 à 11:51, Serge Stinckwich a écrit :
On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo@free.fr> wrote:
Hi guys
I'm fed up to get methods without comments and without little examples. In +1 ! We can setup a small group of people interested to build examples at ESUG.
FileSystem, I wrote most of the comments and I tried to add an obvious example:
basenameWithIndicator "Returns the basename with the indicator appended, i.e. /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo basenameWithIndicator is 'foo/'"
^ self basename , self indicator
Now let us look at:
withExtension: aString ^ self withPath: (self path withExtension: aString)
Nice comment :(
I would like to support PythonDoctest (yes we are not the only one to have ideas let us face is dear friends) +1
https://en.wikipedia.org/wiki/Doctest
def multiply(a, b): """ >>> multiply(4, 3) 12 >>> multiply('a', 3) 'aaa' """ return a * b
Because we can make sure that the comments are accurate.
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
It will help us to have a distinction between printOn: and displayString
Typically
'/tmp/file.txt' asFileReference withExtension: 'log'
printString is bad
since it returns File @ '/tmp/file.log' which is not an reexecutable expression
So let me know what you think. - tell me that we have already test unit (yes the ones I wrote too) => they do not have the same purpose
For me this is getting to be important. Maybe a subset of Pharo could be defined as core with a kind of API freeze, so we can spend some time documenting the corresponding methods and classes.
-- www.tudorgirba.com www.feenk.com
"Every thing has its own flow."
-- www.tudorgirba.com www.feenk.com
"Next time you see your life passing by, say 'hi' and get to know her."
2016-08-18 13:32 GMT+02:00 stepharo <stepharo@free.fr>:
withExtension: aString
"Returns a new file reference with a different file extension"
Does this comment is really needed? I only see extra word "different". And rest is same as method name. IMHO we should rename method to "withDifferentExtension:" and remove comment.
On Thu, Aug 18, 2016 at 11:28 PM, Denis Kudriashov <dionisiydk@gmail.com> wrote:
2016-08-18 13:32 GMT+02:00 stepharo <stepharo@free.fr>:
withExtension: aString
"Returns a new file reference with a different file extension"
Does this comment is really needed? I only see extra word "different". And rest is same as method name. IMHO we should rename method to "withDifferentExtension:" and remove comment.
I think that it is interesting that the comment also says that it will return a FileReference... of course there are other ways to know that, but it is nice that the comment avoids the research/guessing. More over, which is not obvious is that it will *change* the extension, because the "with" prefix could mislead you to think that it will *add* the extension. Maybe we can come up with a better name (withDifferentExtension: works better, I agree) or we need the comment to be explicit about it.
Hi. 2016-08-18 9:34 GMT+02:00 stepharo <stepharo@free.fr>:
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
So let me know what you think. - tell me that we have already test unit (yes the ones I wrote too) => they do not have the same purpose
I am sorry, but I want to said it: we have tests. Why tests are not for same purpose? (I would say they include it). As Tudor said: "they are way too disconnected from the code" And this needs to be solved. We already have nice feature in Nautilus: it shows "test icon" on covered methods. We could extends this idea to simplify test visibility. Proposed solution is much simpler. But how much it is practical? How many code could use it? For simple cases like String methods is super nice. But could you imaging it for Seaside code? or Morphic?
Ok this is your taste. My reality is different. Tests are far far away. I do not see them. They live in a different time zone. They are smart have a boring setup. I want documentation in front on my nose. No extra thinking no extra click Just right there. Stef Le 18/8/16 à 23:14, Denis Kudriashov a écrit :
Hi.
2016-08-18 9:34 GMT+02:00 stepharo <stepharo@free.fr <mailto:stepharo@free.fr>>:
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
So let me know what you think. - tell me that we have already test unit (yes the ones I wrote too) => they do not have the same purpose
I am sorry, but I want to said it: we have tests. Why tests are not for same purpose? (I would say they include it).
As Tudor said:
"they are way too disconnected from the code"
And this needs to be solved. We already have nice feature in Nautilus: it shows "test icon" on covered methods. We could extends this idea to simplify test visibility.
Proposed solution is much simpler. But how much it is practical? How many code could use it? For simple cases like String methods is super nice. But could you imaging it for Seaside code? or Morphic?
I am sorry, but I want to said it: we have tests. Why tests are not for same purpose? (I would say they include it).
As Tudor said:
"they are way too disconnected from the code"
And this needs to be solved. We already have nice feature in Nautilus: it shows "test icon" on covered methods. We could extends this idea to simplify test visibility.
Proposed solution is much simpler. But how much it is practical? How many code could use it? For simple cases like String methods is super nice. But could you imaging it for Seaside code? or Morphic?
The goal is not to replace nor to use that for everything. I'm not looking for the Graal (and tests are not the graal for documentation). I'm looking for something dead simple that helps me to understand little methods. It works in python that they also have tons of other ways to tests (probably even a test system that check on the line level like in Php). So instead of being defensive we should be more open to improvements when we are talking about documentations. Stef
participants (5)
-
Denis Kudriashov -
Nicolas Passerini -
Serge Stinckwich -
stepharo -
Tudor Girba