As you have learned in the text, the process of compiling code changes it into a machine-readable (rather than user-readable) language your computer can then execute. The compiling process ignores any comments entered by the user, as they have no effect on the operation of the program. However, comments within code are valuable to you and any users who will read your code, arguably as important as the code itself.
Always comment your source code fully. You may be tempted to skip this step in the midst of coding because the program and all of its component classes, methods, and objects are fresh in your mind. When you move on to other projects, or return to a half-finished program later, those comments will be invaluable guides. Comments help you avoid much time and anguish trying to understand the code. The importance of commenting is even further underscored when you work with other programmers or when that code will eventually be maintained by someone else. Without thorough commenting, you have already made the job harder for future administrators of the program-before they have laid eyes on the code or even inspected a single method. Clients that cannot make sense of the code they paid for will be far less likely to seek you out for future programming jobs.
Review the sections of the text that refer to comments, including the three different methods you can use to code comments in Java. Next, 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).
You will notice that the quality of the programs and the quality of the programming varies greatly. Try to remember that these open source projects are posted by programmers of all different levels of experience, and the projects are in various stages of development. As such, they do not always embody sound programming practices.
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.
By Day 3, post a response that summarizes your findings. The post should:
- 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.
- Identify the methods within the example program you believe are not sufficiently documented.
- Examine the control flow statements to determine what they do and if their purpose is clearly documented.
- Explain why you feel the current commenting within the project needs improvement.
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.