[Pharo-project] What is a well documented class?

Mariano Martinez Peck marianopeck at gmail.com
Sun Apr 24 14:47:51 CEST 2011


On Sun, Apr 24, 2011 at 5:13 AM, Alexandre Bergel
<alexandre.bergel at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.gforge.inria.fr/pipermail/pharo-project/attachments/20110424/d6f3f6ea/attachment.htm>


More information about the Pharo-project mailing list