Never assume something is 'obvious'. When you have had your head deep in
the code for weeks, everything seems obvious. I'd rather enforce a
convention of short, human readable docs on every function to guide new
eyes through the whole code base, explaining the author's intentions.
What's noise to you could prove invaluable and save hours of confusion for
someone else. Comments are faded back to a dark grey in you editor so that
they can be easily ignored is need be.


On Fri, May 9, 2014 at 11:42 PM, Diego Marcos <notifications@github.com>wrote:

> In apps/camera/js/lib/camera/focus.js:
>
> > +  }
> > +};
> > +
> > +/**
> > + *  Check if the hardware supports touch to focus
> > + */
> > +Focus.prototype.isTouchFocusSupported = function() {
> > +  var maxfocusAreas = this.mozCamera.capabilities.maxFocusAreas;
> > +  var maxMeteringAreas = this.mozCamera.capabilities.maxMeteringAreas;
> > +  if (maxfocusAreas < 1 && maxMeteringAreas < 1) {
> > +    return false;
> > +  }
> > +  return true;
> > +};
> > +
> > +Focus.prototype.updateFocusArea = function(rect, focusDone) {
>
> it's not obvious with the name? You care about putting ifs in one line but
> you don't seem to care about all those functions that have redundant
> useless documentation. Documentation should be the exception to catch the
> eye of the reader indicating that there's something tricky or difficult to
> understand. If 90% of the documentation is noise I stop paying attention
>
> —
> Reply to this email directly or view it on GitHub<https://github.com/mozilla-b2g/gaia/pull/18776/files#r12498976>
> .
>