Hello everyone, this note here is in response to many students stating that particular comments/documentation are pointless and a petty tax on one's grades in CSE 12. This note will go over many (if not all) uses for documentation and explain why each comment or header asked of you in each assignment is necessary. This will also explain why it is justifiable to take off points on someone's assignment if they are not there. I will start with a generalization on why commenting is so important in the computer science field as a whole and then move on to explain the need for file headers, class headers, method headers, and inline comments.
Documentation is important in the field of computer science for 3 reasons: maintainability, explanation of approach, and communication of deliverables. Maintainability is one of the most important reasons for documentation as it allows other people to utilize the code one has provided. Commenting codefiles to have maintainability means that they need to be explained properly for future use of the file and the methods and classes inside. While the current programmer might have an idea what is going on with the current code, in the future, without this maintainability factor, no one will know what the files, classes or methods do. Explanation of approach helps both future programmers and the current one. When one explains their current design patterns of particular methods or classes, one or a future person reading the file may find the logic errors that may occur the current approach. Even if the current approach works acceptably, how can future programmer improve upon one's code if they do not understand its algorithm? Finally, the communication of deliverables is most important for the people grading your assignment (or for your future technical leads or project managers) to see what has been accomplished. How can unit testing be run if no one knows which files do what? How can the managers of particular project know that work is being accomplished at a fast enough rate? One needs to explain what they are doing in each codefile so everyone knows what useful items can be extracted and tested from each individual file.
While seemingly the most useless of comments/documentation, file headers provide an important role in describing what is going on in each codefile. In the development world, these are useful for programmers looking for specific methods in certain files. This file header will tell them the gist of what is in each file, allowing them to locate functionality with ease. In addition, when attempting to find a problem and unable to find the problem using debuggers such as gdb, seeing the gist of each file at the top allows one to easily and quickly traverse from file to file until the troublesome file is found. This should also be the easiest of comments to implement as it simply summarizes the functionality in the file and provides basic information of how it was created. Files without these headers are harder to look at and instead of the ease of searching through each file's use, users of the files will find themselves looking over each file just to look at what it does. Time = money
Class headers are a very important part of programming as they let developers know what each class does. This is essential to each class not only because it helps the developer know what he/she has just completed but for the entire usability of the product. Why would someone pay another to make code that may or may not do the functions or have the functionality required? Each class's use needs to be explained because using these in code, is a costly venture but most definitely useful when used properly. Since one could characterize classes as "grouping together groups of variables and/or functionality that are logically similar in functionality" developers need to know what group this class is referring to and why it is needed. Not having these comments could cause very poor efficiency in maintainability and readability. Such actions in a software engineering group would render one useless as if the rest of the team doesn't know what one's classes do, how can they implement them? How can the use what they don't know? How can they know it even works? Time = money && Data = Space = money
Potentially one of the most useful of comments/documentation items, method headers are extremely essential to everyone who will ever view the code one writes. Each method one writes is the raw working/processing power of the program and to not have a header of this type explaining what each one does will not only make the method usable (as a developer would never use a method that is not commented for he/she does not know what it does or why he/she should use it) but will also make it easier to understand what exactly is going on with the method. Provided that the programmer designing the method knows what he/she is doing, the method header is essential because it explains what each of your program's "engines" do. An example of this is if someone wanted to know how to find a random number, they would look for a method that fit the description, not one that had a proper name or was in the file that made sense. Not placing these shows that either the method is so simple that it does need an explanation (in which this is still wrong because no one knows exactly what is going on) or incompetence in helping the maintainability of one's code. We take off a larger amount of points for these because they are so crucial. Time = money && Readability = time = money && Maintainability = money
Right now, some of these inline comments may seem unneeded or strange to be explaining simple concepts but eventually they will become very useful to all future programmers and even the developer himself/herself. While the current methods in the assignments may seem simple, what happens when they become complicated? One needs to explain the algorithms or specific implementation techniques one has used in code so that it can be fixed or improved in the future. To be frank, the only reason a developer would be looking at actual code is probably because something has gone wrong and he/she needs to get it working. Not only does not having inline comments create a massive inconvenience for anyone who is trying to understand one's code. it also impedes the use of it in other applications as no one is quite sure what is going on with the undocumented code. An example would be a manager trying to use a method someone wrote but its not complicated so rather than pay a developer 60$ an hour for 3 hours to discover how to use a method and how it works, he is going to ask that same developer to write an entire new one commented in a longer period of time so he knows what is going on and how he can reuse this code he has paid for. These are critical for advanced for strange ways of coding. Methods can only be improved if one first knows what the method does and how it works. No inline for advanced functionality = no reusability = no money
Every piece of documentation we ask you to write is not pointless. We would not waste your time, the tutors time and the grader's time if they were not imperative to course learning. Is it wrong to ask why comments are useful? No, we expect you wonder and hopefully this will answer your questions in case you haven't found out yourself already. Since the first day of class we have referred every student to the style and documentation guide on the CSE 12 website and will continue to grade students on this standard. For those who still see comments/documentation as a useless chore, ask developers in the field or perhaps the companies at the job fair about documentation and you will find that it is an essential part of software engineering that needs to improve and in CSE12 we strive to do just that. In addition, the standards that we have on the website are the ones countless students have embodied and are now in the software engineering field. I personally encourage everyone to comment properly on their code as grader's (from my personal experience) love to give out high grades and are even more forgiving when code is properly commented.
You guys can do it, - Samson Tse