Discussion Post-Commenting for Clarity
Go to any open source repository, where software developers collaborate on the development of open source software, and download the code from one or more open source projects. Some potential repositories to explore are: SourceForge (sourceforge.net), JavaForge (javaforge.com), and Google Code (code.google.com)
Examine the source code for one or more open source projects and locate an example in which: (1) the documentation and commenting within the program leaves something to be desired and (2) more than one control flow statement is used. Inspect the code for the individual source files. If you are able to build the project, run the program a few times so you understand what the author of the program was trying to achieve and how the lines of code in the project work. Think about how the commenting could be improved.
Post a response that summarizes your findings. The post should
1. Include a link to the open source project you chose as an example of poor commenting, or attach an example source file to your posting.
2. Identify the methods within the example program you believe are not sufficiently documented.
3. Examine the control flow statements to determine what they do and if their purpose is clearly documented.
4. Explain why you feel the current commenting within the project needs improvement.
5. Copy the example code into your post, replacing or adding detail to the current comments in order to make the program easier for a user to understand.