$self->total++;
# nor
$self->total = $self->total + 1;
[download]

I do see the point in documenting it (not in what the code does, but why it does it)

So this is off topic: bad documentation does not bad code make.

Documenting what the code does isn't bad by itself, it just isn't needed at all if the people supposed to be reading the documentation can program already.

Imagine they can't, that kind of documentation might help them understand what's happening.

Cheers, Sören

If they can't program already, why are they digging around in code?

Over-documentation does make bad code. The documentation in the cases above is highly redundant with the actual code. Humans like some redundancy to keep communication robust, but there is a threshold where it just becomes silly. Flowerbox comments like the above go well past that point.

"There is no shame in being self-taught, only in not trying to learn in the first place." -- Atrus, Myst: The Book of D'ni.

I certainly see this in Perl all the time:
  $self->total( $self->total + 1 );

Before automatically writing this off as being bad code, consider:

• The class has--or appears to have--a public accessor and a public mutator for total.
• The mutator is free to do stuff other than setting total. For example, it might log that fact that total has changed, or it might notify other agents who have registered interest in that aspect of the the instance.
• Subclasses are free to add interesting behavior to mutations of total, even if those mutations are generated internal to the class.

By coding this as   $self->{total}++; you lose these benefits. Sometimes these benefits aren't important, sometimes they're vital. That said, perhaps   $self->increment_total; might have been better.