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 >> >>
