Mailing-List: contact dev-help@cloudstack.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cloudstack.apache.org
Received-SPF: pass (nike.apache.org: domain of santhosh.edukulla@citrix.com
 designates 103.14.252.240 as permitted sender)
From: Santhosh Edukulla <santhosh.edukulla@citrix.com>
To: "dev@cloudstack.apache.org" <dev@cloudstack.apache.org>
Subject: RE: Code Documentation
Thread-Topic: Code Documentation
Thread-Index: AQHPhZI9vQKQM297/02BKbohnc4TRptuntMAgAS0cTo=
Date: Mon, 16 Jun 2014 07:26:59 +0000
Message-ID: 
 <CB688D716959224C95995F52DE5E82423359AA42@SINPEX01CL02.citrite.net>
References: 
 <CB688D716959224C95995F52DE5E824233599946@SINPEX01CL02.citrite.net>,<CANLSSBX9mnUkgufqeDxv9k02_DXizxCGDd-SqWdQP03GREsdag@mail.gmail.com>
In-Reply-To: 
 <CANLSSBX9mnUkgufqeDxv9k02_DXizxCGDd-SqWdQP03GREsdag@mail.gmail.com>
Accept-Language: en-US
Content-Language: en-US
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0

Agreed, If we are referring to proper naming convention for self explaining=
 the code, yes.=20

But, still adding better and more comment strings or doc strings at appropr=
iate places, is not going to harm i believe, it just compliments and aids b=
etter understanding.=20

We used to add specific examples as well under comments to explain its use =
and this can be used to auto generate the docs for easy reading thereafter.=
 Once in practice and visible, its effect will be more clear i believe.

EX:  Api documentation( I mean generate docs through added comments with ex=
amples, returns, inputs etc ) can be generated like this and can easily doc=
ument api usage with examples, today, api documentation is not much there i=
 believe. =20

Regards,
Santhosh
________________________________________
From: rohityadav89@gmail.com [rohityadav89@gmail.com] on behalf of Rohit Ya=
dav [bhaisaab@apache.org]
Sent: Friday, June 13, 2014 10:59 AM
To: dev@cloudstack.apache.org
Subject: Re: Code Documentation

On Wed, Jun 11, 2014 at 9:58 PM, Santhosh Edukulla <
santhosh.edukulla@citrix.com> wrote:

> Hi All,
>
> Many of code areas under CS, currently don't have enough documentation i
> believe, we have few one liner comments at places. But, largely, was
> missing at various code areas.
>
> We in one of our earlier project, used to enforce strictly a template for
> comments\documentation for every new function added. These comments were
> later retrieved automatically to build code documentation easily. This ge=
ts
> enforced during review itself, or otherwise review wont be accepted.  It
> will make the flow lot easier to understand some times i believe.
>
> Please add atleast basic description for every  major
> interface\class\function, description for input\output arguments for
> individual entities.
>

IMO we should prefer writing code so it documents itself and we save
ourselves from maintaining both code and comments.

Regards.


>
> EX: Currently, for below we dont have any comments in general.
>
> public boolean shutdownNetwork(final long networkId, ReservationContext
> context, boolean cleanupElements)
>
>
> Regards,
> Santhosh
>
>