Re: [Pharo-dev] The importance of Class Comments

2014-06-21 Thread Ben Coman
kilon alios wrote: 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. That probably applies more to rearranging

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread kilon alios
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

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread Damien Cassou
On Fri, Jun 20, 2014 at 2:03 PM, kilon alios 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 enthusia

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread kilon alios
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 chapt

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread Freemail
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 a

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread kilon alios
"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 an

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread stepharo
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 co

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread stepharo
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 ? op

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread stepharo
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. +1000 Dont even comment the small ones, commen

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread Sven Van Caekenberghe
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 p

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread kilon alios
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

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread kilon alios
" 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 speci

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread Yuriy Tymchuk
On 20 Jun 2014, at 10:45, Sven Van Caekenberghe 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

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread Sven Van Caekenberghe
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 commen

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread Yuriy Tymchuk
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 wrote: > yes good idea Damien , thank you. Right no

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread kilon alios
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

Re: [Pharo-dev] The importance of Class Comments

2014-06-20 Thread Damien Cassou
On Fri, Jun 20, 2014 at 9:10 AM, kilon alios 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

[Pharo-dev] The importance of Class Comments

2014-06-20 Thread kilon alios
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 , i