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.
+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 <sean@clipperadams.com> 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.
I like to use: Provides .... or 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" <btc@openinworld.com> 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 <sean@clipperadams.com> 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.
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.
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 -- View this message in context: http://forum.world.st/Class-Comment-Template-Suggestion-tp4822890p4824810.ht... Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
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.
-- View this message in context: http://forum.world.st/Class-Comment-Template-Suggestion-tp4822890p4824840.ht... Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
participants (5)
-
Ben Coman -
phil＠highoctane.be -
Richard Sargent -
Sean P. DeNigris -
stepharo