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

Alexandre Bergel alexandre.bergel at me.com
Sun Apr 24 17:57:13 CEST 2011


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








More information about the Pharo-project mailing list