Agreed, If we are referring to proper naming convention for self explaining the code, yes.
But, still adding better and more comment strings or doc strings at appropriate places, is not going to harm i believe, it just compliments and aids better understanding. 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 examples, returns, inputs etc ) can be generated like this and can easily document api usage with examples, today, api documentation is not much there i believe. Regards, Santhosh ________________________________________ From: rohityada...@gmail.com [rohityada...@gmail.com] on behalf of Rohit Yadav [bhais...@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.eduku...@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 gets > 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 > >
