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

Stéphane Ducasse stephane.ducasse at inria.fr
Sun Apr 24 17:42:52 CEST 2011


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




More information about the Pharo-project mailing list