Smalltalk › Pharo › Pharo Smalltalk Developers

Class Comment Template Suggestion

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

Sean P. DeNigris

Class Comment Template Suggestion

Administrator

The class comment template begins: "For the Class part: State the name of the class with one line description: For example, I'm xxx the root of the hierarchy of visitor objects."

Unlike a traditional CRC card, we are already in a live programming environment with good tools! So the class name is duplicated info (the browser already shows this) which will have to be manually changed on a class rename. Also, the specific example provides an implementation detail duplicated by the class hierarchy tree already shown in the browser. I'd like to change it to: "For the Class part: State a one line summary. For example, "I represent a paragraph of text.""

Any objections?

Cheers,
Sean

Ben Coman

Re: Class Comment Template Suggestion

+1 -- I always liked the first person feel I got from Smalltalk class comments. You might add something like comments should be written in "first person from the perspective of the class"

-0.5 -- Maybe the third person CRC style is better for external documentation (?)

cheers -ben

On Wed, Apr 29, 2015 at 9:17 PM, Sean P. DeNigris <[hidden email]> wrote:

The class comment template begins: "For the Class part: State the name of
the class with one line description: For example, I'm xxx the root of the
hierarchy of visitor objects."

Unlike a traditional CRC card, we are already in a live programming
environment with good tools! So the class name is duplicated info (the
browser already shows this) which will have to be manually changed on a
class rename. Also, the specific example provides an implementation detail
duplicated by the class hierarchy tree already shown in the browser. I'd
like to change it to: "For the Class part: State a one line summary. For
example, "I represent a paragraph of text.""

Any objections?

-----
Cheers,
Sean
--
View this message in context: http://forum.world.st/Class-Comment-Template-Suggestion-tp4822890.html
Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.

philippeback

Re: Class Comment Template Suggestion

I like to use:

Provides ....

Enables ...

It is all about focusing on the responsibilities and collaborators.

The first C is already what I am documenting.

So I do not write the name of the class in the comment.

As I reuse/refactor names tend to get wrong.

Le 29 avr. 2015 16:07, "Ben Coman" <[hidden email]> a écrit :

+1 -- I always liked the first person feel I got from Smalltalk class comments. You might add something like comments should be written in "first person from the perspective of the class"

-0.5 -- Maybe the third person CRC style is better for external documentation (?)

cheers -ben

On Wed, Apr 29, 2015 at 9:17 PM, Sean P. DeNigris <[hidden email]> wrote:
The class comment template begins: "For the Class part: State the name of
the class with one line description: For example, I'm xxx the root of the
hierarchy of visitor objects."

Unlike a traditional CRC card, we are already in a live programming
environment with good tools! So the class name is duplicated info (the
browser already shows this) which will have to be manually changed on a
class rename. Also, the specific example provides an implementation detail
duplicated by the class hierarchy tree already shown in the browser. I'd
like to change it to: "For the Class part: State a one line summary. For
example, "I represent a paragraph of text.""

Any objections?

-----
Cheers,
Sean
--
View this message in context: http://forum.world.st/Class-Comment-Template-Suggestion-tp4822890.html
Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.

stepharo

Re: Class Comment Template Suggestion

In reply to this post by Sean P. DeNigris

I have no problem with changing it this is just that we should in
general write much better class comments.

Stef

Le 29/4/15 15:17, Sean P. DeNigris a écrit :

> The class comment template begins: "For the Class part: State the name of
> the class with one line description: For example, I'm xxx the root of the
> hierarchy of visitor objects."
>
> Unlike a traditional CRC card, we are already in a live programming
> environment with good tools! So the class name is duplicated info (the
> browser already shows this) which will have to be manually changed on a
> class rename. Also, the specific example provides an implementation detail
> duplicated by the class hierarchy tree already shown in the browser. I'd
> like to change it to: "For the Class part: State a one line summary. For
> example, "I represent a paragraph of text.""
>
> Any objections?
>
>
>
> -----
> Cheers,
> Sean
> --
> View this message in context: http://forum.world.st/Class-Comment-Template-Suggestion-tp4822890.html
> Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
>
>

Sean P. DeNigris

Re: Class Comment Template Suggestion

Administrator

stepharo wrote

I have no problem with changing it this is just that we should in
general write much better class comments.

Issue 15498: Improve Class Comment Template
https://pharo.fogbugz.com/default.asp?15498

SLICE-Issue-15498-Improve-Class-Comment-Template-SeanDeNigris.1
- Remove class name to avoid duplication hassles (e.g. going out of date when a class is renamed)
- Give better example in the class part. The existing one duplicated inheritance info already available in the browser
- Small copy edits

Cheers,
Sean

Richard Sargent

Re: Class Comment Template Suggestion

Administrator

In reply to this post by stepharo

stepharo wrote

I have no problem with changing it this is just that we should in
general write much better class comments.

This is true for all commentary. :-)

One of the most important things to include in comments and which is usually omitted is the rationale. Explain why the class exists (it may be obvious in many cases; but usually not so obvious to an outsider), when and why you would use the class.

And of course, this doesn't mean we should ignore how to use it.

Stef

Le 29/4/15 15:17, Sean P. DeNigris a écrit :
> The class comment template begins: "For the Class part: State the name of
> the class with one line description: For example, I'm xxx the root of the
> hierarchy of visitor objects."
>
> Unlike a traditional CRC card, we are already in a live programming
> environment with good tools! So the class name is duplicated info (the
> browser already shows this) which will have to be manually changed on a
> class rename. Also, the specific example provides an implementation detail
> duplicated by the class hierarchy tree already shown in the browser. I'd
> like to change it to: "For the Class part: State a one line summary. For
> example, "I represent a paragraph of text.""
>
> Any objections?
>
>
>
> -----
> Cheers,
> Sean
> --
> View this message in context: http://forum.world.st/Class-Comment-Template-Suggestion-tp4822890.html
> Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
>
>