Note 5.6.1.
Unless otherwise stated, all italicized quotes throughout this section are excerpted from the interview with Computer Science faculty members at the University of Puget Sound that informed this section.
Subsection 5.6.1 Writing Code and Code Comments
Purpose.
Coding is the meat of computer science, and comments are critical for communicating what your code does to other users. Though comments are usually short and don’t always contain full sentences, they never-the-less require clear communication of the most important ideas. Comments generally fall into two categories: informal and formal. Informal comments are notes sprinkled throughout the code that annotate the algorithm to make it clearer for anyone who needs to work with it (including your future self!). Because computer code can be incredibly tedious to understand, and because two people will write different algorithms to accomplish the same goal, the purpose of these comments is to make your code more human-readable and to communicate the main ideas and steps in your code, as you would if outlining an essay. Informal comments do not need to follow an official style guide. In fact, they don’t even have to be complete sentences, but they should be clear and easy to understand. Formal comments (such as Javadoc comments in the Java language) explain the functionality and any inputs (parameters) and outputs (returns) of your methods, fields, and classes. They must follow a specific format so that they can be used to generate a webpage outlining the functionality of the code and giving instructions to use it. To write formal comments, carefully follow your professor’s directions and/or provided style guides. Good comments, both informal and formal, should not state obvious parts of your code, such as that you are using a loop; they should convey what the code does, but not unnecessary details about how it does it.
Valued Characteristics.
“All of the writing I give to my students is an attempt to have them practice the skills they will be doing when they are professionals.”
Concise and precise writing are vital for good comments. The comment should include everything someone might need to use the code successfully, but nothing they can tell just from looking at it. One comment for every 4–5 lines of code is generally a good amount, but it can vary depending on the complexity of your work. Comments should tell the user what the code does, but not all of the details of how it does it.
When writing code, efficiency is also highly valued. This doesn’t mean that the shortest code is best, but code that makes the computer do less work, use less space, and run faster (e.g., has smaller time complexity and space complexity) is valued professionally, where the efficiency of your code can cost or save money and impact customer satisfaction. As you code, think about ways to eliminate redundant code and use less computer memory. In the earlier days of computing, when memory was expensive, writing compact code was an important skill. However, in modern times the professional value of human readable and intuitive code is much higher.
Conventions and Tips.
- Exact formatting, down to use of punctuation and white space, is critical in formal commenting and coding because a computer needs to be able to generate a documentation website from what you write. Read and use style guides to make sure your comments are properly formatted!
- The number of informal comments you should have throughout your code varies with the complexity of the code you are annotating and the language you are writing in. When writing in Java, a higher-level (more human-readable) language, you can expect to comment on average every 4–5 lines. However, when writing assembly code, which is much lower-level (and consequently difficult to read), it is standard to comment every line of code.
- Many CS classes involve pair or group programming. When working with others, be sure to set yourself up to share the work equally. Choose a workspace where everyone is involved and pass the computer back and forth between logical units. Be self aware about the amount and ways you contribute, and give your partner space to contribute. Be open-minded and curious about what your partner has to add to the project.
- Write your comments as you write your code, even if you need to go back and alter them later, rather than hurriedly adding them right before turning in your assignment. As you write longer and more complicated code and work as part of a team of programmers, it will be increasingly difficult to remember what your idea was when writing old code, and your colleagues will need to stay updated on your code as you write it because their code may depend on your implementation.
Note 5.6.2. Coding and academic honesty.
Code is a form of writing, and, even when programming a simple task, one person’s code differs from another’s in the same way essays differ. While tons of code is available online (such as on Stack Overflow) and sharing code is useful in more advanced projects, copying someone’s code without crediting them is plagiarism (see Section 8.2). If you are unsure about whether you can use code you found online or elsewhere, always ask your professor.
Additional Resources.
google.github.io/styleguide/javaguide.htmlgoogle.github.io/styleguide/cppguide.htmlgoogle.github.io/styleguide/objcguide.htmlgoogle.github.io/styleguide/
