The importance of Class Comments
I completely understand the inability to create full blown documentation because of lack of free time. I am not referring to any Pharo Library out there. Please pharo developers comment your classes. Dont even comment the small ones, comment the big ones (over 20 methods). 5 minutes per class , is 150 words (assuming you are a slow 30 words/per minute , 3 times more if you type fast). Just a class comment, I can live without method comments. 15 lines, enough to provide valuable information to your users. Even for very big libraries like Spec it should not take more than 10 key classes to be documented this way , no more than 1 hour total of documentation for a project that can take months of coding to complete. It can't be this hard. Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me . Have a nice day :)
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote:
Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment. -- Damien Cassou http://damiencassou.seasidehosting.st "Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too. Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ? On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou <damien.cassou@gmail.com> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote:
Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
I have not worked with spec a lot, but I think that itâs nice in terms of comments, they are very helpful. Also lately Iâve worked with Roassal2 - no comments at all, but you can ask Alex for help :) Uko On 20 Jun 2014, at 10:06, kilon alios <kilon.alios@gmail.com> wrote:
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ?
On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou <damien.cassou@gmail.com> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote: Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
I am a bit offended by the generalisations in your remarks, Kilon. It sounds a bit like there is no documentation at all. There are several books, covering many of the high level aspects. There is lots of documentation in the image, many class comments are pretty good, as are many method comments - even quite a lot of implementation comments can be found. OK, there are some terrible parts as well, and some people seems to make a sport out of _not_ writing any comments at all - please call them out specifically, but don't generalise. I have spent a large amount of time documenting all code that I published as well as writing separate high level documentation and tutorials for most of it as well as for Pharo in general. I know many others who did the same. On 20 Jun 2014, at 10:10, Yuriy Tymchuk <yuriy.tymchuk@me.com> wrote:
I have not worked with spec a lot, but I think that itâs nice in terms of comments, they are very helpful. Also lately Iâve worked with Roassal2 - no comments at all, but you can ask Alex for help :)
Uko
On 20 Jun 2014, at 10:06, kilon alios <kilon.alios@gmail.com> wrote:
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ?
On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou <damien.cassou@gmail.com> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote: Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
On 20 Jun 2014, at 10:45, Sven Van Caekenberghe <sven@stfx.eu> wrote:
I am a bit offended by the generalisations in your remarks, Kilon. It sounds a bit like there is no documentation at all.
There are several books, covering many of the high level aspects.
There is lots of documentation in the image, many class comments are pretty good, as are many method comments - even quite a lot of implementation comments can be found.
OK, there are some terrible parts as well, and some people seems to make a sport out of _not_ writing any comments at all - please call them out specifically, but don't generalise.
Thantâs why we have to reject slices without commented classes :). Anyway I hope that red exclamation marks to their job. Uko
I have spent a large amount of time documenting all code that I published as well as writing separate high level documentation and tutorials for most of it as well as for Pharo in general. I know many others who did the same.
On 20 Jun 2014, at 10:10, Yuriy Tymchuk <yuriy.tymchuk@me.com> wrote:
I have not worked with spec a lot, but I think that itâs nice in terms of comments, they are very helpful. Also lately Iâve worked with Roassal2 - no comments at all, but you can ask Alex for help :)
Uko
On 20 Jun 2014, at 10:06, kilon alios <kilon.alios@gmail.com> wrote:
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ?
On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou <damien.cassou@gmail.com> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote: Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
" It sounds a bit like there is no documentation at all" Î never implied this, and I refuse to believe that my wording can sound like that. I just say that the class comments are usually too small and many important classes are not documented at all. I don't know why you think I targeted you specifically with my comments. "terrible parts" is not the word I will use. I find the lack of documentation frustrating but that does not make the classes themselves "terrible". Pharo has its fair share of messy code but I have failed to see something I would call terrible. Its awesome that you spent large amount of time documenting, but all I said is that documenting key classes in the range of 10-15 lines each should not take a lot of time and pharo developers should do it. Thats my opinion, you are more than welcome to disagree or ignore it. I am willing to help any way I can. I am not willing to put blame on people. I do feel however because I believe I am a logical person that people that are introduced to Pharo will be disappointed in this department as I am. I think this is unfair to Pharo, because you guys have put a lot of effort in it that partly goes to waste. Imagine what would happen if people had easy access to the libraries , how many more would contribute and help pharo. I cannot imagine where I would be if there was no PBE or PFTE or the class comments that already are in there. For me any form of documentation is like bread and butter. Am I unreasonable ? I hope not. On Fri, Jun 20, 2014 at 11:45 AM, Sven Van Caekenberghe <sven@stfx.eu> wrote:
I am a bit offended by the generalisations in your remarks, Kilon. It sounds a bit like there is no documentation at all.
There are several books, covering many of the high level aspects.
There is lots of documentation in the image, many class comments are pretty good, as are many method comments - even quite a lot of implementation comments can be found.
OK, there are some terrible parts as well, and some people seems to make a sport out of _not_ writing any comments at all - please call them out specifically, but don't generalise.
I have spent a large amount of time documenting all code that I published as well as writing separate high level documentation and tutorials for most of it as well as for Pharo in general. I know many others who did the same.
On 20 Jun 2014, at 10:10, Yuriy Tymchuk <yuriy.tymchuk@me.com> wrote:
I have not worked with spec a lot, but I think that itâs nice in terms of comments, they are very helpful. Also lately Iâve worked with Roassal2 - no comments at all, but you can ask Alex for help :)
Uko
On 20 Jun 2014, at 10:06, kilon alios <kilon.alios@gmail.com> wrote:
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ?
On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou < damien.cassou@gmail.com> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote: Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
You are not targeting me, you are targeting everybody, that is why I, as a member of this community trying to improve things, feel offended. By saying 'the class comments are not good', you imply all of them. If I say 'people from country X are lazy' or even 'many/most of them are lazy', most people of that country, especially those who are definitively not will be rightfully offended. It is a generalisation that creates a bad reputation which is unfair. Of course you don't have to call out individual people, but if there are large packages out there (inside Pharo even) with 10s or 100s of classes with zero comments, then we as users have every right to say WTF !? And for me, those are terrible parts (with respects to documentation), because it is very hard to even start looking at the code and find your way. Spec _is_ partially documented - the website www.spec.org and the papers are pretty good - it took Ben and Johan lots of time and I appreciate that a lot. The problem of Spec is that it is a bit strange, hard to get your finger on (it is a UI specification, abstraction and composition layer, not a GUI toolkit as such). It confuses people (things are called model, but these are UI models, not domain models). Furthermore, it evolved a lot so that there are historic inconsistencies between current code, examples and documentation. But I know you are helping to improve Pharo, especially around documentation, so I am not angry at all - I know for a fact that the situation around documentation has been improving a lot, and improvements accelerated in the last year. On 20 Jun 2014, at 12:17, kilon alios <kilon.alios@gmail.com> wrote:
" It sounds a bit like there is no documentation at all"
Î never implied this, and I refuse to believe that my wording can sound like that. I just say that the class comments are usually too small and many important classes are not documented at all. I don't know why you think I targeted you specifically with my comments.
"terrible parts" is not the word I will use. I find the lack of documentation frustrating but that does not make the classes themselves "terrible". Pharo has its fair share of messy code but I have failed to see something I would call terrible.
Its awesome that you spent large amount of time documenting, but all I said is that documenting key classes in the range of 10-15 lines each should not take a lot of time and pharo developers should do it. Thats my opinion, you are more than welcome to disagree or ignore it.
I am willing to help any way I can. I am not willing to put blame on people.
I do feel however because I believe I am a logical person that people that are introduced to Pharo will be disappointed in this department as I am. I think this is unfair to Pharo, because you guys have put a lot of effort in it that partly goes to waste. Imagine what would happen if people had easy access to the libraries , how many more would contribute and help pharo.
I cannot imagine where I would be if there was no PBE or PFTE or the class comments that already are in there. For me any form of documentation is like bread and butter.
Am I unreasonable ?
I hope not.
On Fri, Jun 20, 2014 at 11:45 AM, Sven Van Caekenberghe <sven@stfx.eu> wrote: I am a bit offended by the generalisations in your remarks, Kilon. It sounds a bit like there is no documentation at all.
There are several books, covering many of the high level aspects.
There is lots of documentation in the image, many class comments are pretty good, as are many method comments - even quite a lot of implementation comments can be found.
OK, there are some terrible parts as well, and some people seems to make a sport out of _not_ writing any comments at all - please call them out specifically, but don't generalise.
I have spent a large amount of time documenting all code that I published as well as writing separate high level documentation and tutorials for most of it as well as for Pharo in general. I know many others who did the same.
On 20 Jun 2014, at 10:10, Yuriy Tymchuk <yuriy.tymchuk@me.com> wrote:
I have not worked with spec a lot, but I think that itâs nice in terms of comments, they are very helpful. Also lately Iâve worked with Roassal2 - no comments at all, but you can ask Alex for help :)
Uko
On 20 Jun 2014, at 10:06, kilon alios <kilon.alios@gmail.com> wrote:
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ?
On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou <damien.cassou@gmail.com> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote: Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
"If I say 'people from country X are lazy' or even 'many/most of them are lazy', most people of that country, especially those who are definitively not will be rightfully offended. It is a generalisation that creates a bad reputation which is unfair." As a Greek believe me I can sympathize with anyone been called "lazy" , I would never dare to believe that Pharo developers are lazy. I think , and this is only an assumption, that coders and not just pharo coders, love to improve their code and they see documentation as something that it takes them away from what they love doing. So for me at least is not a question of laziness. The problem is that I cannot state a negative opinion without the possibility of someone being offended. "open a bug entry." thanks Stephan I will do so :) On Fri, Jun 20, 2014 at 1:47 PM, Sven Van Caekenberghe <sven@stfx.eu> wrote:
You are not targeting me, you are targeting everybody, that is why I, as a member of this community trying to improve things, feel offended.
By saying 'the class comments are not good', you imply all of them.
If I say 'people from country X are lazy' or even 'many/most of them are lazy', most people of that country, especially those who are definitively not will be rightfully offended. It is a generalisation that creates a bad reputation which is unfair.
Of course you don't have to call out individual people, but if there are large packages out there (inside Pharo even) with 10s or 100s of classes with zero comments, then we as users have every right to say WTF !? And for me, those are terrible parts (with respects to documentation), because it is very hard to even start looking at the code and find your way.
Spec _is_ partially documented - the website www.spec.org and the papers are pretty good - it took Ben and Johan lots of time and I appreciate that a lot.
The problem of Spec is that it is a bit strange, hard to get your finger on (it is a UI specification, abstraction and composition layer, not a GUI toolkit as such). It confuses people (things are called model, but these are UI models, not domain models). Furthermore, it evolved a lot so that there are historic inconsistencies between current code, examples and documentation.
But I know you are helping to improve Pharo, especially around documentation, so I am not angry at all - I know for a fact that the situation around documentation has been improving a lot, and improvements accelerated in the last year.
On 20 Jun 2014, at 12:17, kilon alios <kilon.alios@gmail.com> wrote:
" It sounds a bit like there is no documentation at all"
Î never implied this, and I refuse to believe that my wording can sound like that. I just say that the class comments are usually too small and many important classes are not documented at all. I don't know why you think I targeted you specifically with my comments.
"terrible parts" is not the word I will use. I find the lack of documentation frustrating but that does not make the classes themselves "terrible". Pharo has its fair share of messy code but I have failed to see something I would call terrible.
Its awesome that you spent large amount of time documenting, but all I said is that documenting key classes in the range of 10-15 lines each should not take a lot of time and pharo developers should do it. Thats my opinion, you are more than welcome to disagree or ignore it.
I am willing to help any way I can. I am not willing to put blame on people.
I do feel however because I believe I am a logical person that people that are introduced to Pharo will be disappointed in this department as I am. I think this is unfair to Pharo, because you guys have put a lot of effort in it that partly goes to waste. Imagine what would happen if people had easy access to the libraries , how many more would contribute and help pharo.
I cannot imagine where I would be if there was no PBE or PFTE or the class comments that already are in there. For me any form of documentation is like bread and butter.
Am I unreasonable ?
I hope not.
On Fri, Jun 20, 2014 at 11:45 AM, Sven Van Caekenberghe <sven@stfx.eu> wrote: I am a bit offended by the generalisations in your remarks, Kilon. It sounds a bit like there is no documentation at all.
There are several books, covering many of the high level aspects.
There is lots of documentation in the image, many class comments are pretty good, as are many method comments - even quite a lot of implementation comments can be found.
OK, there are some terrible parts as well, and some people seems to make a sport out of _not_ writing any comments at all - please call them out specifically, but don't generalise.
I have spent a large amount of time documenting all code that I published as well as writing separate high level documentation and tutorials for most of it as well as for Pharo in general. I know many others who did the same.
On 20 Jun 2014, at 10:10, Yuriy Tymchuk <yuriy.tymchuk@me.com> wrote:
I have not worked with spec a lot, but I think that itâs nice in terms of comments, they are very helpful. Also lately Iâve worked with Roassal2 - no comments at all, but you can ask Alex for help :)
Uko
On 20 Jun 2014, at 10:06, kilon alios <kilon.alios@gmail.com> wrote:
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ?
On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou < damien.cassou@gmail.com> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote: Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
Documentation is not that bad. Good parts are definitly pharo by example, for the enterprise and deep into pharo. But roassal2 for example has many undocumented classes. I am willing to help here. At the moment I am trying to get all athens examples to work. And of course, people in this list are really helpful, but it would be good, if problems and solutions don't get lost in this mailinglist. Nicolai On Fri Jun 20 12:47:24 2014 Sven Van Caekenberghe <sven@stfx.eu> wrote:
You are not targeting me, you are targeting everybody, that is why I, as a member of this community trying to improve things, feel offended.
By saying 'the class comments are not good', you imply all of them.
If I say 'people from country X are lazy' or even 'many/most of them are lazy', most people of that country, especially those who are definitively not will be rightfully offended. It is a generalisation that creates a bad reputation which is unfair.
Of course you don't have to call out individual people, but if there are large packages out there (inside Pharo even) with 10s or 100s of classes with zero comments, then we as users have every right to say WTF !? And for me, those are terrible parts (with respects to documentation), because it is very hard to even start looking at the code and find your way.
Spec _is_ partially documented - the website www.spec.org and the papers are pretty good - it took Ben and Johan lots of time and I appreciate that a lot.
The problem of Spec is that it is a bit strange, hard to get your finger on (it is a UI specification, abstraction and composition layer, not a GUI toolkit as such). It confuses people (things are called model, but these are UI models, not domain models). Furthermore, it evolved a lot so that there are historic inconsistencies between current code, examples and documentation.
But I know you are helping to improve Pharo, especially around documentation, so I am not angry at all - I know for a fact that the situation around documentation has been improving a lot, and improvements accelerated in the last year.
On 20 Jun 2014, at 12:17, kilon alios <kilon.alios@gmail.com> wrote:
" It sounds a bit like there is no documentation at all"
Î never implied this, and I refuse to believe that my wording can sound like that. I just say that the class comments are usually too small and many important classes are not documented at all. I don't know why you think I targeted you specifically with my comments.
"terrible parts" is not the word I will use. I find the lack of documentation frustrating but that does not make the classes themselves "terrible". Pharo has its fair share of messy code but I have failed to see something I would call terrible.
Its awesome that you spent large amount of time documenting, but all I said is that documenting key classes in the range of 10-15 lines each should not take a lot of time and pharo developers should do it. Thats my opinion, you are more than welcome to disagree or ignore it.
I am willing to help any way I can. I am not willing to put blame on people.
I do feel however because I believe I am a logical person that people that are introduced to Pharo will be disappointed in this department as I am. I think this is unfair to Pharo, because you guys have put a lot of effort in it that partly goes to waste. Imagine what would happen if people had easy access to the libraries , how many more would contribute and help pharo.
I cannot imagine where I would be if there was no PBE or PFTE or the class comments that already are in there. For me any form of documentation is like bread and butter.
Am I unreasonable ?
I hope not.
On Fri, Jun 20, 2014 at 11:45 AM, Sven Van Caekenberghe <sven@stfx.eu> wrote: I am a bit offended by the generalisations in your remarks, Kilon. It sounds a bit like there is no documentation at all.
There are several books, covering many of the high level aspects.
There is lots of documentation in the image, many class comments are pretty good, as are many method comments - even quite a lot of implementation comments can be found.
OK, there are some terrible parts as well, and some people seems to make a sport out of _not_ writing any comments at all - please call them out specifically, but don't generalise.
I have spent a large amount of time documenting all code that I published as well as writing separate high level documentation and tutorials for most of it as well as for Pharo in general. I know many others who did the same.
On 20 Jun 2014, at 10:10, Yuriy Tymchuk <yuriy.tymchuk@me.com> wrote:
I have not worked with spec a lot, but I think that itâs nice in terms of comments, they are very helpful. Also lately Iâve worked with Roassal2 - no comments at all, but you can ask Alex for help :)
Uko
On 20 Jun 2014, at 10:06, kilon alios <kilon.alios@gmail.com> wrote:
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ?
On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou <damien.cassou@gmail.com> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote: Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
yes I have bought PBE and Deep Into Pharo and I have read at least 3 times each book , I love them. The documentation is well written. PFTE is turning into a well written Pharo bible, so yeah things are going very well on documentation front. I am helping with porting PBE to Pharo 3, first 3 chapters are already ported. I will start chapter 4 sortly. I think the one thing that misses in PBE is a chapter on Object Orientation. The book assumes that the coder is already familiar with OOP and so the chapters are not beginner friendly for people not used to OOP. I am considering making a chapter about it fairly soon. I will add it to my "Pharo Universe" book that has a repo here https://github.com/kilon/Pharo-Universe and people can get the pdf here https://ci.inria.fr/pharo-contribution/job/PharoUniverse/lastSuccessfulBuild... I also have translated the chapter on Pharo Sound from PFTE which is also included in the book as a separate chapter. I have not checked the automatic translation from google so mistakes may be inside. On Fri, Jun 20, 2014 at 2:42 PM, Freemail <nicolaihess@web.de> wrote:
Documentation is not that bad. Good parts are definitly pharo by example, for the enterprise and deep into pharo. But roassal2 for example has many undocumented classes. I am willing to help here.
At the moment I am trying to get all athens examples to work.
And of course, people in this list are really helpful, but it would be good, if problems and solutions don't get lost in this mailinglist.
Nicolai
On Fri Jun 20 12:47:24 2014 Sven Van Caekenberghe <sven@stfx.eu> wrote:
You are not targeting me, you are targeting everybody, that is why I, as a member of this community trying to improve things, feel offended.
By saying 'the class comments are not good', you imply all of them.
If I say 'people from country X are lazy' or even 'many/most of them are lazy', most people of that country, especially those who are definitively not will be rightfully offended. It is a generalisation that creates a bad reputation which is unfair.
Of course you don't have to call out individual people, but if there are large packages out there (inside Pharo even) with 10s or 100s of classes with zero comments, then we as users have every right to say WTF !? And for me, those are terrible parts (with respects to documentation), because it is very hard to even start looking at the code and find your way.
Spec _is_ partially documented - the website www.spec.org and the papers are pretty good - it took Ben and Johan lots of time and I appreciate that a lot.
The problem of Spec is that it is a bit strange, hard to get your finger on (it is a UI specification, abstraction and composition layer, not a GUI toolkit as such). It confuses people (things are called model, but these are UI models, not domain models). Furthermore, it evolved a lot so that there are historic inconsistencies between current code, examples and documentation.
But I know you are helping to improve Pharo, especially around documentation, so I am not angry at all - I know for a fact that the situation around documentation has been improving a lot, and improvements accelerated in the last year.
On 20 Jun 2014, at 12:17, kilon alios <kilon.alios@gmail.com> wrote:
" It sounds a bit like there is no documentation at all"
Î never implied this, and I refuse to believe that my wording can sound like that. I just say that the class comments are usually too small and many important classes are not documented at all. I don't know why you think I targeted you specifically with my comments.
"terrible parts" is not the word I will use. I find the lack of documentation frustrating but that does not make the classes themselves "terrible". Pharo has its fair share of messy code but I have failed to see something I would call terrible.
Its awesome that you spent large amount of time documenting, but all I said is that documenting key classes in the range of 10-15 lines each should not take a lot of time and pharo developers should do it. Thats my opinion, you are more than welcome to disagree or ignore it.
I am willing to help any way I can. I am not willing to put blame on people.
I do feel however because I believe I am a logical person that people that are introduced to Pharo will be disappointed in this department as I am. I think this is unfair to Pharo, because you guys have put a lot of effort in it that partly goes to waste. Imagine what would happen if people had easy access to the libraries , how many more would contribute and help pharo.
I cannot imagine where I would be if there was no PBE or PFTE or the class comments that already are in there. For me any form of documentation is like bread and butter.
Am I unreasonable ?
I hope not.
On Fri, Jun 20, 2014 at 11:45 AM, Sven Van Caekenberghe <sven@stfx.eu>
wrote: I am a bit offended by the generalisations in your remarks, Kilon. It sounds a bit like there is no documentation at all.
There are several books, covering many of the high level aspects.
There is lots of documentation in the image, many class comments are pretty good, as are many method comments - even quite a lot of implementation comments can be found.
OK, there are some terrible parts as well, and some people seems to make a sport out of _not_ writing any comments at all - please call them out specifically, but don't generalise.
I have spent a large amount of time documenting all code that I published as well as writing separate high level documentation and tutorials for most of it as well as for Pharo in general. I know many others who did the same.
On 20 Jun 2014, at 10:10, Yuriy Tymchuk <yuriy.tymchuk@me.com> wrote:
I have not worked with spec a lot, but I think that itâs nice in terms of comments, they are very helpful. Also lately Iâve worked with Roassal2 - no comments at all, but you can ask Alex for help :)
Uko
On 20 Jun 2014, at 10:06, kilon alios <kilon.alios@gmail.com> wrote:
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ?
On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou <damien.cassou@gmail.com> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote: Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
On Fri, Jun 20, 2014 at 2:03 PM, kilon alios <kilon.alios@gmail.com> wrote:
am considering making a chapter about it fairly soon.
what about putting this chapter in UpdatedPBE? -- Damien Cassou http://damiencassou.seasidehosting.st "Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
I don't have an issue with that but Stephane Ducasse asked me not to change PBE and only do necessary porting to Pharo 3 so people that have done the translations for it will have easier time porting their translations too. The chapter will be based on a chapter I have created for a book teaching Python for Blender users which can be found here --> http://wiki.blender.org/index.php/User:Kilon/Python_book_of_magic/09.Object Of course a lot of things need to change because Python is a different language and I want to also show the Pharo IDE tools. Now time to try your auto conversion tool on chapter 4 of PBE ;) On Fri, Jun 20, 2014 at 4:03 PM, Damien Cassou <damien.cassou@gmail.com> wrote:
On Fri, Jun 20, 2014 at 2:03 PM, kilon alios <kilon.alios@gmail.com> wrote:
am considering making a chapter about it fairly soon.
what about putting this chapter in UpdatedPBE?
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
I think some Spec class comments could be bigger maybe with a couple of sort examples. Now that we have an online reference for Pharo it would be important if class comments are lengthier even if the information is covered in the PFTE Spec tutorial. But I will investigate further to see what I can propose in terms of actual comments. On Fri, Jun 20, 2014 at 11:10 AM, Yuriy Tymchuk <yuriy.tymchuk@me.com> wrote:
I have not worked with spec a lot, but I think that itâs nice in terms of comments, they are very helpful. Also lately Iâve worked with Roassal2 - no comments at all, but you can ask Alex for help :)
Uko
On 20 Jun 2014, at 10:06, kilon alios <kilon.alios@gmail.com> wrote:
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ?
On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou <damien.cassou@gmail.com> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com> wrote:
Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
The problem is that documenting frameworks is difficult. You should build cookbook. stef On 20/6/14 12:21, kilon alios wrote:
I think some Spec class comments could be bigger maybe with a couple of sort examples. Now that we have an online reference for Pharo it would be important if class comments are lengthier even if the information is covered in the PFTE Spec tutorial. But I will investigate further to see what I can propose in terms of actual comments.
On Fri, Jun 20, 2014 at 11:10 AM, Yuriy Tymchuk <yuriy.tymchuk@me.com <mailto:yuriy.tymchuk@me.com>> wrote:
I have not worked with spec a lot, but I think that itâs nice in terms of comments, they are very helpful. Also lately Iâve worked with Roassal2 - no comments at all, but you can ask Alex for help :)
Uko
On 20 Jun 2014, at 10:06, kilon alios <kilon.alios@gmail.com <mailto:kilon.alios@gmail.com>> wrote:
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
Should I open also an issue on the bug tracker with a slice of my class comment ? Or is posting it here enough ?
On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou <damien.cassou@gmail.com <mailto:damien.cassou@gmail.com>> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com <mailto:kilon.alios@gmail.com>> wrote:
Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st <http://damiencassou.seasidehosting.st/>
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
On 20/6/14 10:06, kilon alios wrote:
yes good idea Damien , thank you. Right now I am working with Rubric building a new workspace tool basing it on the rubric example. Spec and Morphic are on my list too.
Should I open also an issue on the bug tracker with a slice of my class comment ?
open a bug entry.
Or is posting it here enough ?
On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou <damien.cassou@gmail.com <mailto:damien.cassou@gmail.com>> wrote:
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios <kilon.alios@gmail.com <mailto:kilon.alios@gmail.com>> wrote:
Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
I suggest that you ask on this mailing list when you would like to have documentation on a class and you can't write it yourself. That way, we all will read the answer. Hopefully, someone, will merge this and write a class comment.
-- Damien Cassou http://damiencassou.seasidehosting.st
"Success is the ability to go from one failure to another without losing enthusiasm." Winston Churchill
On 20/6/14 09:10, kilon alios wrote:
I completely understand the inability to create full blown documentation because of lack of free time. I am not referring to any Pharo Library out there. Please pharo developers comment your classes.
+10000000
Dont even comment the small ones, comment the big ones (over 20 methods). 5 minutes per class , is 150 words (assuming you are a slow 30 words/per minute , 3 times more if you type fast). Just a class comment, I can live without method comments. 15 lines, enough to provide valuable information to your users.
Even for very big libraries like Spec it should not take more than 10 key classes to be documented this way , no more than 1 hour total of documentation for a project that can take months of coding to complete. It can't be this hard.
Saying that I will start adding class comments wherever I can but obviously the people that have created the code are far more qualified than me .
Have a nice day :)
participants (7)
-
Ben Coman -
Damien Cassou -
Freemail -
kilon alios -
stepharo -
Sven Van Caekenberghe -
Yuriy Tymchuk