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

Stéphane Ducasse stephane.ducasse at inria.fr
Sun Apr 24 11:03:37 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


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




More information about the Pharo-project mailing list