RE: Code Documentation
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
Re: Code Documentation
IMO, comments are part of code. By writing code comments, we aren’t maintaining comments and code but rather helping others understand what the code is doing. As a developer, if I can easily understand what the code is doing, I won’t even look at the comments. In our codebase we have functions which easily span more than thousand lines of code. scanning each and every conditional for all the possible scenarios is very difficult and tiresome. If we have a codebase which follows some conventions, it would be very easy to read code. But, in the current state we are faaar from ideal. We can use a tool like doxygen(i don’t know if available for java) to generate documentation from source code. Infact, anyone interested can run the doxygen build locally and use. but, this tool is of no use if we don’t improve the code documentation/standards. ~Rajani On 13-Jun-2014, at 8:29 pm, Rohit Yadav bhais...@apache.org wrote: 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
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
Code Documentation
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. EX: Currently, for below we dont have any comments in general. public boolean shutdownNetwork(final long networkId, ReservationContext context, boolean cleanupElements) Regards, Santhosh
