Try to have it so users don't have to delete much, just extend what is there.
On Tue, May 12, 2015 at 2:10 AM, Kasper Osterbye <kas...@itu.dk> wrote: > Sergio Fedi and I are now working on this. > > As part of the work, we need a "default package comment", akin the the > default class comment. The class comment is inspired by CRC idea. > Translating CRC to a PRC, we suggest the following, and ask for comments > from the community. As I believe we will by the end of the year have a > inworld pillar renderer which is fairly stable, the default PRC template > could be: > 'Please comment me using the following ""template"", ''inspired'' by Class > Responsibility Collaborator (CRC) design: > 'inspired'' by Class Responsibility Collaborator (CRC) design, written in first-person narrative: > > !Package XXX, part of (reference to main package if one exist) > one line description: For example, I'm xxx package, containing the > hierarchy > of visitor objects. > One line description: I'm Xyz package, providing widgets that ... (Leave "Part of package" for Collaborators (see below) ) > > ;Responsibiliies > :Three sentences about my main responsibility, what I'm doing, what classes > do I offer. > (Three sentences is not much to talk about all the package's classes. How about...) I offer services for ... > ;Collaborators :State my related packages, and which classes are the ones used from the > outside of the package. > I'm part of Abc package ... My related packages are ... My entry points are ... > !!Public API > - message one in class one > - message two in class two > - what is the way to use this package. > > One simple example is simply gorgeous. Or refer to which package is the > main package if there are several packages in play > > !!Internal Representation and Key Implementation Points. > > -Implementation Points, in particular references to classes with good class > comments.' > > Will this work? > > Nice initiative. cheers -ben
