Re: [wmii] wmii-3 on MacOS X?

On 6/16/06, Anselm R. Garbe <garbeam_AT_wmii.de> wrote:
> On Thu, Jun 15, 2006 at 08:47:12PM -0400, Geoffrey Alan Washburn wrote:
> > Also, just because the goal is an efficient and lean window manager
> > doesn't mean you shouldn't include any comments in your code. It is
> > really inexcusable to not at least have comments explaining what a
> > function does, if not comments on the logic. Proper documentation would
> > have saved me a lot of effort. However, given how little code is
> > actually there, it is rather tempting to rewrite it in proper language.
>
> I agree that several portions should be commented properly, but
> only those which do unobvious things or which might be easier to
> understand if the context is commented. Comments like
>
> /* focuses client c. */
> void
> focus_client(Client *c)
> {
> ...
> }
>
> are quite useless, because the function name already documents
> its purpose. Same applies to variable names. Comments about the
> logic like
>
> /* loops 100 times */
> for(i=0; i < 100; i++) {
> ...
> }
>
> are quite useless as well, because it is obvious what the loop
> does. However, comments make sense if they describe the
> context of a specific function or algorithm.
>
> At least no comments are better than wrong or verbose ascii art
> which make the code lesser readable or might be total
> misleading.

You are right with that, but whenever I make somebody read you code I
get complaints about the missing documentation. So maybe you should at
least consider to document parts of it. The simple comments can savely
be left out, but *please* document what is not obvious.

-- 
mit freundlichen Grüßen
                  Steffen Liebergeld