Comments

Jason Johnson jason.johnson.081 at gmail.com
Wed Sep 12 05:15:37 UTC 2007


Ah, well that is a good point.

On 9/12/07, Andreas Raab <andreas.raab at gmx.de> wrote:
> Jason Johnson wrote:
> > It truly is annoying when you look at classes with no comments.
> > Writers of classes need to remember that the next person looking at
> > the code doesn't have the whole architecture in their head like you do
> > so they may not know where to start.
> >
> > But "every method should" is an exaggeration, no?  I mean do you want
> > a comment for every accessors saying "this is an accessors"?
>
> No, it should say what the variable is good for. We had this discussion
> here recently and I have to admit that there is something to be said for
> putting variable comments into the accessors instead of the class
> comment (where they are much harder to find and to update). In an
> optimal solution these would be automatically synchronized so the
> comment of the accessors would be  the comments of the variable and vice
> versa. Here is a good example from our code base:
>
> cacheLocally
>         "Boolean - if true, tells the system to maintain a locally cached copy
> of the document file."
>         ^ cacheLocally
>
> Cheers,
>    - Andreas
>
> >
> > In any event, Squeak could certainly use more commenting.
> >
> > On 9/12/07, Andreas Raab <andreas.raab at gmx.de> wrote:
> >> Steven W Riggins wrote:
> >>> Likewise, I feel every method should start with a comment, and this
> >>> nonsense about the method selector being good enough to define intention
> >>> just tossed out of the equation.  Show me a party where you can pass 1-4
> >>> words between 15 people and get the same 1-4 words at the end. :)
> >>> However, several sentences can be better, or not depending on the
> >>> engineer, but at least it is a start.
> >> Amen, brother.
> >>
> >> Cheers,
> >>    - Andreas
> >>
> >>
> >
> >
>
>
>



More information about the Squeak-dev mailing list