[Pharo-project] What is a well documented class?
Hi! I am dreaming about a tool to help me document source code. The question I have is what is a well documented class? What do you think about the following: A well documented class is a class: - that contains a class comment - its class comments contains either an example, or an associated unit test - without 'as yet unclassified' method category - each public method belongs to a method category named public* - each private method belongs to a method category named private* - each method contains a comment, located before the declaration of temporary variables - other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public' - without commented code contained in its methods. Is there anything else? Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
for the class comment I would have intention I'm doing that collaborations with the help of this class and that class main api my main public API is ... my subclasses may want to override such specific hooks ... Implementation notes iv and their purposes
Hi!
I am dreaming about a tool to help me document source code. The question I have is what is a well documented class? What do you think about the following:
A well documented class is a class: - that contains a class comment - its class comments contains either an example, or an associated unit test - without 'as yet unclassified' method category - each public method belongs to a method category named public* - each private method belongs to a method category named private* - each method contains a comment, located before the declaration of temporary variables - other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public' - without commented code contained in its methods.
Is there anything else?
Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
On Sun, Apr 24, 2011 at 4:03 AM, Stéphane Ducasse <stephane.ducasse@inria.fr> wrote:
for the class comment I would have
intention     I'm doing that collaborations     with the help of this class and that class main api     my main public API is ...
    my subclasses may want to override such specific hooks ...
Yes, yes! I would like to see those suggestions used by the default comment template for new classes.
Implementation notes     iv and their purposes
May I ask, what if we stopped ever mentioning instance vars in the class comment? Perhaps it's a problem of having only one place to document both external and internal details of the class, but it really irks me when the comment template for a newly created class suggests that I divulge the implementation details in what appears to be a document of the interface. Moreover, the comment must change when the implementation changes, even if the interface remains the same. Perhaps that's why so many class comments seem out of sync with the current state of their classes. Thoughts? Mike
Implementation notes iv and their purposes
May I ask, what if we stopped ever mentioning instance vars in the class comment? Perhaps it's a problem of having only one place to document both external and internal details of the class, but it really irks me when the comment template for a newly created class suggests that I divulge the implementation details in what appears to be a document of the interface. Moreover, the comment must change when the implementation changes, even if the interface remains the same. Perhaps that's why so many class comments seem out of sync with the current state of their classes.
Indeed. Synchronizing the documentation and the code is a problem. Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
May I ask, what if we stopped ever mentioning instance vars in the class comment? Perhaps it's a problem of having only one place to document both external and internal details of the class, but it really irks me when the comment template for a newly created class suggests that I divulge the implementation details in what appears to be a document of the interface. Moreover, the comment must change when the implementation changes, even if the interface remains the same. Perhaps that's why so many class comments seem out of sync with the current state of their classes.
Indeed. Synchronizing the documentation and the code is a problem.
yes but.... let us write more comments. All the rest is arguments not to write them which is far easier as usual. Stef
Stéphane Ducasse wrote:
yes but.... let us write more comments. All the rest is arguments not to write them which is far easier as usual.
Stef
Absolutely. Sorry, I didn't mean to imply otherwise. Mike -- View this message in context: http://forum.world.st/What-is-a-well-documented-class-tp3470956p3475730.html Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
I did not imply anything special. I just remember when lukas started to write comments on seaside while I was driving on the high way to Nice. I said ok let us start :) But I regularly got burned by comments absence and I spend time writing them because I like when the code tell: stef you are so smart, you guess well what I'm doing. Because comments are about reinforcement of hypothesis. Stef
Stéphane Ducasse wrote:
yes but.... let us write more comments. All the rest is arguments not to write them which is far easier as usual.
Stef
Absolutely. Sorry, I didn't mean to imply otherwise.
Mike
-- View this message in context: http://forum.world.st/What-is-a-well-documented-class-tp3470956p3475730.html Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
for the class comment I would have
intention I'm doing that collaborations with the help of this class and that class main api my main public API is ...
my subclasses may want to override such specific hooks ...
Implementation notes iv and their purposes
Yes! The collaborations and main api may be automatically inferred (from unit tests?) The public interface can also be inferred. I will work on this. Alexandre
Hi!
I am dreaming about a tool to help me document source code. The question I have is what is a well documented class? What do you think about the following:
A well documented class is a class: - that contains a class comment - its class comments contains either an example, or an associated unit test - without 'as yet unclassified' method category - each public method belongs to a method category named public* - each private method belongs to a method category named private* - each method contains a comment, located before the declaration of temporary variables - other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public' - without commented code contained in its methods.
Is there anything else?
Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
first let us start changing the default class comment template to have these sections. Stef On Apr 24, 2011, at 5:57 PM, Alexandre Bergel wrote:
for the class comment I would have
intention I'm doing that collaborations with the help of this class and that class main api my main public API is ...
my subclasses may want to override such specific hooks ...
Implementation notes iv and their purposes
Yes! The collaborations and main api may be automatically inferred (from unit tests?) The public interface can also be inferred. I will work on this.
Alexandre
Hi!
I am dreaming about a tool to help me document source code. The question I have is what is a well documented class? What do you think about the following:
A well documented class is a class: - that contains a class comment - its class comments contains either an example, or an associated unit test - without 'as yet unclassified' method category - each public method belongs to a method category named public* - each private method belongs to a method category named private* - each method contains a comment, located before the declaration of temporary variables - other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public' - without commented code contained in its methods.
Is there anything else?
Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
On Sun, Apr 24, 2011 at 5:13 AM, Alexandre Bergel <alexandre.bergel@me.com>wrote:
Hi!
I am dreaming about a tool to help me document source code. The question I have is what is a well documented class? What do you think about the following:
A well documented class is a class: - that contains a class comment - its class comments contains either an example, or an associated unit test
yes but sometimes the mapping is not "one to one" between classes and methods
- without 'as yet unclassified' method category - each public method belongs to a method category named public*
For me no. that's just a convention you may use. I don't put all my public methods in public*
- each private method belongs to a method category named private*
the same here..sometimes in put them in private* but soemtimes no.
- each method contains a comment, located before the declaration of temporary variables
It depends if it is worth it or not. Putting a comment that explains exactly the same than the code is not worth it if the method is "self explanatory". Anyway, millions of times you do need to put comments and they help.
- other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public'
this sounds too java for me.
- without commented code contained in its methods.
Is there anything else?
For me, when dealing with frameworks where there are "base" clases that one can subclass and make its own concrete subclass, it is NEVER documented which methods should I implement. What I mean is that I really like (and I do it) to create a superclass with all the necessary methods as ^ self subclassResponsability (yes, kind of Java interface). cheers mariano
Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- Mariano http://marianopeck.wordpress.com
- without 'as yet unclassified' method category - each public method belongs to a method category named public*
For me no. that's just a convention you may use. I don't put all my public methods in public*
But if you have a tool that does it automatically for you, will you use it?
- each private method belongs to a method category named private*
the same here..sometimes in put them in private* but soemtimes no.
Ok, but I am not really talking how you should write you code, but how you would like to read code that you haven't written. Will it help to have public* and private* categories?
- each method contains a comment, located before the declaration of temporary variables
It depends if it is worth it or not. Putting a comment that explains exactly the same than the code is not worth it if the method is "self explanatory". Anyway, millions of times you do need to put comments and they help.
I appreciate Lukas' code. It is full of comments.
- other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public'
this sounds too java for me.
Indeed.
- without commented code contained in its methods.
Is there anything else?
For me, when dealing with frameworks where there are "base" clases that one can subclass and make its own concrete subclass, it is NEVER documented which methods should I implement. What I mean is that I really like (and I do it) to create a superclass with all the necessary methods as ^ self subclassResponsability (yes, kind of Java interface).
Yes, the class comment can contains what are the necessary methods to overload. Cheers, Alexandre
cheers
mariano
Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- Mariano http://marianopeck.wordpress.com
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
On Sat, Apr 23, 2011 at 10:13 PM, Alexandre Bergel <alexandre.bergel@me.com> wrote: [...]
 - each public method belongs to a method category named public*  - each private method belongs to a method category named private*
Others here may disagree -- and the dreary of legislating and enforcing conventions aside -- but I strive (usually with success) to move all privately-used methods to one or more delegates. One class's private method is just another's public???
 - other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public'
Again, I sympathise with facing the visibility problem, but I don't trust that conventions will be upheld by either end, so I tire of following them. Replace Pharo/Squeak categories with Newspeak modules; replace Pharo/Squeak protocols with traits (stateless, please); I'll be the first in line. My 0.25 :-) Mike
- each public method belongs to a method category named public* - each private method belongs to a method category named private*
Others here may disagree -- and the dreary of legislating and enforcing conventions aside -- but I strive (usually with success) to move all privately-used methods to one or more delegates. One class's private method is just another's public???
A private method may have to access instances variables. Moving the method to another class may be difficult sometimes.
- other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public'
Again, I sympathise with facing the visibility problem, but I don't trust that conventions will be upheld by either end, so I tire of following them. Replace Pharo/Squeak categories with Newspeak modules; replace Pharo/Squeak protocols with traits (stateless, please); I'll be the first in line.
I do not think this should be enforced. It is easy to infer method visibility with a set of well defined scenarios, for example the one that comes in unit tests. Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
Alex give a try and see. I think that this is important. We can even publish something out of it :) Stef On Apr 24, 2011, at 6:17 PM, Alexandre Bergel wrote:
- each public method belongs to a method category named public* - each private method belongs to a method category named private*
Others here may disagree -- and the dreary of legislating and enforcing conventions aside -- but I strive (usually with success) to move all privately-used methods to one or more delegates. One class's private method is just another's public???
A private method may have to access instances variables. Moving the method to another class may be difficult sometimes.
- other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public'
Again, I sympathise with facing the visibility problem, but I don't trust that conventions will be upheld by either end, so I tire of following them. Replace Pharo/Squeak categories with Newspeak modules; replace Pharo/Squeak protocols with traits (stateless, please); I'll be the first in line.
I do not think this should be enforced. It is easy to infer method visibility with a set of well defined scenarios, for example the one that comes in unit tests.
Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
give a try and see. I think that this is important.
Yes it is.
We can even publish something out of it :)
That's a side effect that cannot be avoided :-) Alexandre
On Apr 24, 2011, at 6:17 PM, Alexandre Bergel wrote:
- each public method belongs to a method category named public* - each private method belongs to a method category named private*
Others here may disagree -- and the dreary of legislating and enforcing conventions aside -- but I strive (usually with success) to move all privately-used methods to one or more delegates. One class's private method is just another's public???
A private method may have to access instances variables. Moving the method to another class may be difficult sometimes.
- other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public'
Again, I sympathise with facing the visibility problem, but I don't trust that conventions will be upheld by either end, so I tire of following them. Replace Pharo/Squeak categories with Newspeak modules; replace Pharo/Squeak protocols with traits (stateless, please); I'll be the first in line.
I do not think this should be enforced. It is easy to infer method visibility with a set of well defined scenarios, for example the one that comes in unit tests.
Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
On Apr 24, 2011, at 6:49 PM, Alexandre Bergel wrote:
give a try and see. I think that this is important.
Yes it is.
We can even publish something out of it :)
That's a side effect that cannot be avoided :-)
;-) so even better.
Alexandre
On Apr 24, 2011, at 6:17 PM, Alexandre Bergel wrote:
- each public method belongs to a method category named public* - each private method belongs to a method category named private*
Others here may disagree -- and the dreary of legislating and enforcing conventions aside -- but I strive (usually with success) to move all privately-used methods to one or more delegates. One class's private method is just another's public???
A private method may have to access instances variables. Moving the method to another class may be difficult sometimes.
- other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public'
Again, I sympathise with facing the visibility problem, but I don't trust that conventions will be upheld by either end, so I tire of following them. Replace Pharo/Squeak categories with Newspeak modules; replace Pharo/Squeak protocols with traits (stateless, please); I'll be the first in line.
I do not think this should be enforced. It is easy to infer method visibility with a set of well defined scenarios, for example the one that comes in unit tests.
Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
Public/private categories would a lot of sense if methods could belong to more than one category. Dolphin allows that, and it's *really* nice. ________________________________________ From: pharo-project-bounces@lists.gforge.inria.fr [pharo-project-bounces@lists.gforge.inria.fr] On Behalf Of Stéphane Ducasse [stephane.ducasse@inria.fr] Sent: Sunday, April 24, 2011 12:37 PM To: Pharo-project@lists.gforge.inria.fr Subject: Re: [Pharo-project] What is a well documented class? On Apr 24, 2011, at 6:49 PM, Alexandre Bergel wrote:
give a try and see. I think that this is important.
Yes it is.
We can even publish something out of it :)
That's a side effect that cannot be avoided :-)
;-) so even better.
Alexandre
On Apr 24, 2011, at 6:17 PM, Alexandre Bergel wrote:
- each public method belongs to a method category named public* - each private method belongs to a method category named private*
Others here may disagree -- and the dreary of legislating and enforcing conventions aside -- but I strive (usually with success) to move all privately-used methods to one or more delegates. One class's private method is just another's public???
A private method may have to access instances variables. Moving the method to another class may be difficult sometimes.
- other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public'
Again, I sympathise with facing the visibility problem, but I don't trust that conventions will be upheld by either end, so I tire of following them. Replace Pharo/Squeak categories with Newspeak modules; replace Pharo/Squeak protocols with traits (stateless, please); I'll be the first in line.
I do not think this should be enforced. It is easy to infer method visibility with a set of well defined scenarios, for example the one that comes in unit tests.
Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
So, instead of having public/private category, a comment can be "public method" or "private method". I will work on a documentation tool very soon. Cheers, Alexandre On 24 Apr 2011, at 12:45, Schwab,Wilhelm K wrote:
Public/private categories would a lot of sense if methods could belong to more than one category. Dolphin allows that, and it's *really* nice.
________________________________________ From: pharo-project-bounces@lists.gforge.inria.fr [pharo-project-bounces@lists.gforge.inria.fr] On Behalf Of Stéphane Ducasse [stephane.ducasse@inria.fr] Sent: Sunday, April 24, 2011 12:37 PM To: Pharo-project@lists.gforge.inria.fr Subject: Re: [Pharo-project] What is a well documented class?
On Apr 24, 2011, at 6:49 PM, Alexandre Bergel wrote:
give a try and see. I think that this is important.
Yes it is.
We can even publish something out of it :)
That's a side effect that cannot be avoided :-)
;-) so even better.
Alexandre
On Apr 24, 2011, at 6:17 PM, Alexandre Bergel wrote:
- each public method belongs to a method category named public* - each private method belongs to a method category named private*
Others here may disagree -- and the dreary of legislating and enforcing conventions aside -- but I strive (usually with success) to move all privately-used methods to one or more delegates. One class's private method is just another's public???
A private method may have to access instances variables. Moving the method to another class may be difficult sometimes.
- other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public'
Again, I sympathise with facing the visibility problem, but I don't trust that conventions will be upheld by either end, so I tire of following them. Replace Pharo/Squeak categories with Newspeak modules; replace Pharo/Squeak protocols with traits (stateless, please); I'll be the first in line.
I do not think this should be enforced. It is easy to infer method visibility with a set of well defined scenarios, for example the one that comes in unit tests.
Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
On Sun, Apr 24, 2011 at 11:17 AM, Alexandre Bergel <alexandre.bergel@me.com> wrote:
 - each public method belongs to a method category named public*  - each private method belongs to a method category named private*
Others here may disagree -- and the dreary of legislating and enforcing conventions aside -- but I strive (usually with success) to move all privately-used methods to one or more delegates. Â One class's private method is just another's public???
A private method may have to access instances variables. Moving the method to another class may be difficult sometimes.
All the more reason to move it! A private method accessing instance variables is just global-variable-oriented spaghetti programming disguised by a class. Such a method is just begging to be moved to a delegate and to accept the instance var values as arguments.
 - other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public'
Again, I sympathise with facing the visibility problem, but I don't trust that conventions will be upheld by either end, so I tire of following them. Â Replace Pharo/Squeak categories with Newspeak modules; replace Pharo/Squeak protocols with traits (stateless, please); I'll be the first in line.
I do not think this should be enforced. It is easy to infer method visibility with a set of well defined scenarios, for example the one that comes in unit tests.
You can't infer reliably from such shaky premises, whether they are manifest as conventions or unit tests. Cheers, Mike
I think a well documented class is a class which can be understood by reading its documentation without having to resort to anything else, be it running the test only to see something not obvious, reading the code to understand the working which the document fell short; and without having to assemble a mini encyclopedia of references in order to grasp the contents of the documentation. my 0.019999 -- Cesar Rabak
Ok, but what would be a tool that help you write comment? This cannot be the system browser. Alexandre On 25 Apr 2011, at 12:37, csrabak@bol.com.br wrote:
I think a well documented class is a class which can be understood by reading its documentation without having to resort to anything else, be it running the test only to see something not obvious, reading the code to understand the working which the document fell short; and without having to assemble a mini encyclopedia of references in order to grasp the contents of the documentation.
my 0.019999
-- Cesar Rabak
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
The tool is a text editor ;-) If we agree on my suggestions, we can compose a set of guidelines to arrive at deliverables that comply with them. One tool could be a template and a checklist to help the writer of the documentation. -- Cesar Rabak Em 25/04/2011 14:59, Alexandre Bergel < alexandre.bergel@me.com > escreveu: Ok, but what would be a tool that help you write comment? This cannot be the system browser. Alexandre On 25 Apr 2011, at 12:37, csrabak@bol.com.br wrote:
I think a well documented class is a class which can be understood by reading its documentation without having to resort to anything else, be it running the test only to see something not obvious, reading the code to understand the working which the document fell short; and without having to assemble a mini encyclopedia of references in order to grasp the contents of the documentation.
my 0.019999
-- Cesar Rabak
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
The tool is a text editor ;-)
Woooaaa... That can't be :-) please check the email I just sent. Alexandre
If we agree on my suggestions, we can compose a set of guidelines to arrive at deliverables that comply with them.
One tool could be a template and a checklist to help the writer of the documentation.
-- Cesar Rabak
Em 25/04/2011 14:59, Alexandre Bergel < alexandre.bergel@me.com > escreveu: Ok, but what would be a tool that help you write comment? This cannot be the system browser.
Alexandre
On 25 Apr 2011, at 12:37, csrabak@bol.com.br wrote:
I think a well documented class is a class which can be understood by reading its documentation without having to resort to anything else, be it running the test only to see something not obvious, reading the code to understand the working which the document fell short; and without having to assemble a mini encyclopedia of references in order to grasp the contents of the documentation.
my 0.019999
-- Cesar Rabak
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
2cents about "what is a well-documented class?": Information about the state variables (instance variables): what goes in the slot, and what it's for. Good examples (the layout gets skewed doing copy/paste) in RxsPredicate Instance Variables: predicate <BlockClosure> A one-argument block. If it evaluates to the value defined by <negated> when it is passed a character, the predicate is considered to match. negation <BlockClosure> A one-argument block that is a negation of <predicate>. SMxMorph Structure: instance var Type Description bounds Rectangle A Rectangle indicating my position and a size that will enclose me. owner SMxMorph My parent SMxMorph, or nil for the top-level SMxMorph, which is a or nil world, typically a SMxPasteUpMorph. submorphs Array My child Morphs. fullBounds Rectangle A Rectangle minimally enclosing me and my submorphs. color Color My primary color. Subclasses can use this in different ways. extension SMxMorphExtension Allows extra properties to be stored without adding a or nil storage burden to all morphs. -- View this message in context: http://forum.world.st/What-is-a-well-documented-class-tp3470956p3474024.html Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
Ok, focusing on the instance variables. I think there is two kind of documentation, one for the casual user, and another for the developers. Alexandre On 25 Apr 2011, at 16:09, DougEdmunds wrote:
2cents about "what is a well-documented class?":
Information about the state variables (instance variables): what goes in the slot, and what it's for.
Good examples (the layout gets skewed doing copy/paste)
in RxsPredicate
Instance Variables:
predicate <BlockClosure> A one-argument block. If it evaluates to the value defined by <negated> when it is passed a character, the predicate is considered to match.
negation <BlockClosure> A one-argument block that is a negation of <predicate>.
SMxMorph
Structure: instance var Type Description bounds Rectangle A Rectangle indicating my position and a size that will enclose me.
owner SMxMorph My parent SMxMorph, or nil for the top-level SMxMorph, which is a or nil world, typically a SMxPasteUpMorph.
submorphs Array My child Morphs.
fullBounds Rectangle A Rectangle minimally enclosing me and my submorphs.
color Color My primary color. Subclasses can use this in different ways.
extension SMxMorphExtension Allows extra properties to be stored without adding a or nil storage burden to all morphs.
-- View this message in context: http://forum.world.st/What-is-a-well-documented-class-tp3470956p3474024.html Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
What would be a "casual user" of a class in Smalltalk? -- Cesar Rabak Em 25/04/2011 18:19, Alexandre Bergel < alexandre.bergel@me.com > escreveu: Ok, focusing on the instance variables. I think there is two kind of documentation, one for the casual user, and another for the developers. Alexandre On 25 Apr 2011, at 16:09, DougEdmunds wrote:
2cents about "what is a well-documented class?":
Information about the state variables (instance variables): what goes in the slot, and what it's for.
Good examples (the layout gets skewed doing copy/paste)
in RxsPredicate
Instance Variables:
predicate A one-argument block. If it evaluates to the value defined by when it is passed a character, the predicate is considered to match.
negation A one-argument block that is a negation of .
SMxMorph
Structure: instance var Type Description bounds Rectangle A Rectangle indicating my position and a size that will enclose me.
owner SMxMorph My parent SMxMorph, or nil for the top-level SMxMorph, which is a or nil world, typically a SMxPasteUpMorph.
submorphs Array My child Morphs.
fullBounds Rectangle A Rectangle minimally enclosing me and my submorphs.
color Color My primary color. Subclasses can use this in different ways.
extension SMxMorphExtension Allows extra properties to be stored without adding a or nil storage burden to all morphs.
-- View this message in context: http://forum.world.st/What-is-a-well-documented-class-tp3470956p3474024.html Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
What would be a "casual user" of a class in Smalltalk?
Someone who does not care about the type of instances variables of that particular class :-) Alexandre
Em 25/04/2011 18:19, Alexandre Bergel < alexandre.bergel@me.com > escreveu: Ok, focusing on the instance variables. I think there is two kind of documentation, one for the casual user, and another for the developers.
Alexandre
On 25 Apr 2011, at 16:09, DougEdmunds wrote:
2cents about "what is a well-documented class?":
Information about the state variables (instance variables): what goes in the slot, and what it's for.
Good examples (the layout gets skewed doing copy/paste)
in RxsPredicate
Instance Variables:
predicate A one-argument block. If it evaluates to the value defined by when it is passed a character, the predicate is considered to match.
negation A one-argument block that is a negation of .
SMxMorph
Structure: instance var Type Description bounds Rectangle A Rectangle indicating my position and a size that will enclose me.
owner SMxMorph My parent SMxMorph, or nil for the top-level SMxMorph, which is a or nil world, typically a SMxPasteUpMorph.
submorphs Array My child Morphs.
fullBounds Rectangle A Rectangle minimally enclosing me and my submorphs.
color Color My primary color. Subclasses can use this in different ways.
extension SMxMorphExtension Allows extra properties to be stored without adding a or nil storage burden to all morphs.
-- View this message in context: http://forum.world.st/What-is-a-well-documented-class-tp3470956p3474024.html Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
participants (8)
-
Alexandre Bergel -
csrabak＠bol.com.br -
DougEdmunds -
Mariano Martinez Peck -
Michael Forster -
Michael J. Forster
-
Schwab,Wilhelm K -
Stéphane Ducasse