[Pharo-project] What is a well documented class?
alexandre.bergel at me.com
Sun Apr 24 17:57:13 CEST 2011
> for the class comment I would have
> I'm doing that
> 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.
>> 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?
>> Alexandre Bergel http://www.bergel.eu
Alexandre Bergel http://www.bergel.eu
More information about the Pharo-project