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

Alexandre Bergel alexandre.bergel at me.com
Sun Apr 24 18:07:30 CEST 2011


>  - 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
^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.








More information about the Pharo-project mailing list