Comments (was: Python)

"Michael F. Stemper" <[email protected]> wrote or quoted:
>The bad news? I knew enough German to be able to tell that the two paired
>comments sometimes disagreed on what was being done or how it was done.

  Comments in two different languages seem to be add additional
  workload and a distraction with little benefit. Every programmer
  can read and write English.

  There are several types of comments:

  - documentation comments tell callers how to use a feature
    documenting its interfaces,

  - implementation comments explain how an implementation
    accomplishes (implements) a given interface,

  - work comments contain notes for programmers helping them
    build and change the code, such as "todo: . . .", "fixme:
    . . ."), etc., and

  - log comments provide a history of the project and of edit
    sessions.

  Implementation comments should not try to reduplicate what the
  code obviously does, but rather explain, what a piece of code
  is /intended/ to do and /why/ certain choices where made.

Newsgroups: comp.lang.python