- The ICS Robocode Standards
- The ICS Coding Standards
- The Elements of Java Style,by Allan Vermeulen, Scott Ambler, et al.
My edited code can be found here.
Coding standards are important because they promote understanding of a program, both by future users as well as the author. Programmers who carefully implement coding standards create code that works as it was designed to, because they document the purpose of each piece of a program. Furthermore, if the meaning of something is altered in the programming process, the programmer will become aware of such changes as variable, method, and class names no longer make sense. Coding standards are important because it creates a uniform work that can be read more easily by others. Even if people use slightly different coding standards, they will still be able to more easily adapt to a single style within a programming project than a programming style that jumps everywhere. Coding standards promote neat, organized code, and these characteristics will always increase the readability of a program.
For me, the editing process was relatively painless, since I had taken the time to organize and comment my code for the first submission. The two major things that I needed to do were to import the ICS SE Eclipse formatting file, which would provide a template for my code in Eclipse, including using spaces instead of hard tabs. Although this was something I had to do only once for the entire assignment, it was significant because I had no idea that it was possible to define your own formatting within Eclipse, much less how I could go about doing so.
Second, I had to edit the comments within my files. The biggest change was that I had to add in JavaDoc comments. Prior to this class, I honestly had no idea what a JavaDoc comment was, and before this specific assignment, I really didn't know how to use them. I'm actually surprised that none of my introductory Java courses at UH taught us about the JavaDoc comments; I remember my teachers emphasizing commenting, but we didn't learn anything about commenting conventions or JavaDocs. In my original submission, I had used JavaDoc comments once or twice without much thought; mostly copying the style of comments when I was working off a sample robot. A lot of the edits amounted to adding in the extra asterisk at the start of my comments and reorganizing what I had so that the first sentence was the best stand-alone description of what the robot did. It was good practice for me, though, and I think that I'll find it a lot more intuitive to write JavaDoc comments this way from the start in future assignments.
Another main change I had to make to my program's comments was to re-write them to be in third-person active voice. I don't feel like I have ever used a standard voice when writing comments, so this will give me a good base to work from in the future. One commenting standard that I have not used previously was using end-of-line comments to describe the purpose of a variable. In the past, I have worried that it would be too messy and confusing, but after being consistent about using end-of-line comments throughout the project, I can appreciate the fact that they make it much easier to determine the purpose of a variable.
Finally, I'd like to include a few observations I made while reformatting my Robocode project. First, I love Eclipse's "refactor" tool, which allows one to easily rename a project or a variable within a Java document. I had a few variable names that either no longer aptly described the variable's purpose, or were not formatted correctly, and it was extremely easy to change the names of these variables and feel confident that I had made all of the necessary changes. I did run into a problem, however, when starting up Robocode to test some changes I had made - Robocode was set to look for the robots in the newly non-existent project directory, Robocode. I had to rename my project back to the original name, open up Robocode, then rename the project to the correct one for the standards, and then edit the directory where Robocode would look for robot files. It was a complicated process, but I'm glad that I did catch it right away, because I would probably have panicked if I hadn't discovered the problem until later.
Next, I realized that the smallest things can trip you up, even when "just" editing. I decided to try to better optimize some of my implementations for the movement functions, as I noted that I wanted to in my previous blog entry. For the most part, I was able to get everything to work together without a hitch after looking at Edward Meyer's code. However, my robot that was supposed to move between all four corners would just not go in the correct direction when it was supposed to navigate between the top left and bottom right corners. I easily spent half an hour trying to figure out where I changed the code, which was simply a specific adaptation of my already-working code to move the robot to the center of the field. The final verdict? I had somehow deleted an end parenthesis to end a nested function, and had solved the problem by tacking on a parenthesis at the end of the line.
Overall, I feel that this assignment was an extremely valuable learning process. Although it required little to no actual coding, it showed me that the comments for a program are just as important as the code itself. Moreover, I now have guidelines available, so that it will be easier for me to write uniform comments on future programming projects. I think that formatting programs correctly will be much easier when the coding standards are enforced from the beginning, and this exercise will serve as a reminder of the importance of getting it right (or as close to right as possible) the first time through.
Important links referenced in this post:
No comments:
Post a Comment