music

OSdata.com

comments

summary

    Comments are extra information intended for human readers of a program.

    The person reading the comments might include yourself, because it is surprisingly easy to forget how complicated code works just days after you initially wrote it.

    A humorous rule of thumb is to assume that the next programmer maintaining your software is an axe-wielding psychopath who knows where you live. Avoid anything that would cause the axe murderer to hunt you down. Comment to keep the axe murderer calm.

    The general rule is to add useful comments.

    Don’t simply repeat the same information that is obvious in the code itself.

   $counter++; /* increment the counter */

    Use comments to describe the methods being used.

    /* this routine will perform a breadth first search of the input graph */
    /* to find the shortest path between nodes u and v */

    An important exception to the no obvious comments rule is the use of comments to label an item or group of items so they can easily be found later. In the following example, the declarations make it immediately obvious that this is a collection of global variables, but the word “GLOBALS” can be searched to quickly find the collection (there might be many uses of the global keyword throughout the code).

/******************************/
/* GLOBALS                    */
/******************************/
global $visitorresult;
global $adminflag;
global $websitename;

free computer programming text book project table of contents If you like the idea of this project, then please donate some money. more information on donating

comments

    Comments are extra information intended for human readers of a program. A compiler or interpretter ignores comments (or converts them into whitespace).

    A computer doesn’t need comments. You could write a program without any comments and your compiler won’t care. Any human trying to read your program will care.

    Students often have trouble understanding why there is such an emphasis on comments. It seems like busy work.

    The truth is that any program small enough to be used as a teaching assignment is probably so trivial that any competent programmer could look at the raw uncommented source code and figure out exactly how the program works.

    Students rarely ever have to go back and modify a class assignment after it has been turned in for a grade.

    In real life, successful programs last for years or decades. There will be a need for many different programmers will have to make modifications to a program long after the initial coding. In addition to any bug fixes, there will be new features added and changes in response to external conditions.

    In the life cycle of non-trivial programs, the vast majority of the time and effort is in the maintenance of the program, not the initial design and coding.

    Sooner or later the programmer making the changes will be someone different than the original programmer. Comments are the basic tool that the next programmer will use in figuring out how to make these inevitable changes.

    In the earliest days of computers there was a tendency to believe that programs would be written once and used for a brief period and then abandoned for new work.

    Programmers started to realize that they were redoing work that they or someone else had already done. Reinventing the wheel. This led to the creation of libraries of code that all the programmers at a particular installation could share.

    In order for the libraries to be useful, the programmer who wrote each library routine would have to leave behind some kind of documentation for other programmers to know what the library routine did and how to use it in their own programs.

    External documentation included such things as a manual (or manual entry), flow charts, pseudocode, and numerous other paper documents.

    Internal documentation included comments and naming things so that the name was meaningful.

    In the first decades of computer programming, there was an emphasis on external documentation. Unfortunately, external documentation turned out to be unreliable.

    In some cases the documentation was created before the program was written (such as a flow chart or pseudocode). When the actual software inevitably changed (as errors were located or new requirements were added by the bosses), the original flowcharts and other documentation wouldn’t get changed. Sometimes the differences were minor annoyances. Sometimes the differences were major problems to the next programmer to work on the project.

    If writing the external documentation was saved for after the actual coding, it would often be a sloppy afterthought. The programmer, anxious to get on to the next job, would rush through the creation of the external documentation. Important information would get left out. Sometimes incorrect information would be written down. Sometimes things would be simplified to the point of being useless. Often the programmer would simply not write any external documentation of any kind. And inevitably external documentation would have a tendency of getting lost or misplaced or even discarded.

    Because of the inherent unreliability of external documentation, current software engineering emphasizes well written internal documentation. Internal documentation cna easily be updated as the program is being written. And comments are the primary method for internal documentation.

creating comments

    There are four basic kinds of comments (not all languages support all four methods).

    Comments can exist on separate lines (a single line of comment only). For some early langagues, this is the only option available.

    Comments can exist over a series of multiple lines.

    Comments can exist at the end of a line.

    Comments can appear in the midst of a line.

    A possible source of confusion is different methods for indicating a comment. For example, in Pascal, a comment can be indicated by placing it between braces or curly brackets { Pascal comment }. But in C, the curly brackets or braces are used to indicate a block of code. These kinds of differences are one reason that it is best that a beginning student only learn one programming language at a time.

    Important: As a beginning student, only read the one language section that discusses the language you are learning. Attempting to learn multiple languages at once is a recipe for disaster.

C

Pascal

PHP

ALGOL

Ruby

in-line comments

    Use comments throughout your program to let yourself or others know what is going on. Even if the program is solely for your own use, you may have trouble remembering important details a year or more after you write it.

    Some programmers add a comment to the end of every line, often repeating the same information as the source code with slightly different language. This is a complete waste of time.

; BAD COMMENT!
MOV D0, D5     ; move the contents of the D5 register into the D0 register
RET

    Add comments when they add information to the source code.

; GOOD COMMENT!
MOV D0, D5     ; grand total stored in D0 as function result in preparation for return
RET

    Use comments liberally throughout your source code to explain everything that you might forget or that another programmer will need to know to understand your code.

header comments

    Procedures, functions, and other important blocks of code, as well as the beginning of programs, should have header comments that fully explain the purpose of the code, any conventions for using the code, and important information about the code that another programmer will need to understand.

    Many working installations will have particular required formats for header comments. Most professors will have detailed requirements for header comments. Follow those required formats exactly as specified.

    If your installation does not have a required format for header comments, go ahead and use a format that you are familar with (possibly one you learned in school).

    I can not over emphasize the importance of good header comments.

    The following example is from an assembly language routine, but it illustrates the basic idea.

;***********************************************************
;* FUNCTION NAME: Hexadecimal_Character_to_Binary
;* PURPOSE: Converts an ASCII character into its binary 4-bit equivalent
;* INPUTS: D0 register has an ASCII character in the ranges 0..9 or A..F or a..f
;*      space character translated into zero
;* OUTPUT D0.B register has a hexadecimal integer
;*      of nibble (4-bit) length
;*      entire register zero filled
;*      if invalid input, D0.L set to -1
;*      N flag cleared on successful translation
;*      N flag set on failure (invalid hex)
;* METHODS: Uses a table look-up for fast translation
;* REGISTERS: All registers other than D0 are preserved.
;* CALLS: none
;* CALLED BY: UTILITY routine widely used
;***********************************************************

    There are three common methods for indicating a block of comments (examples shown only in C to save space, the principles are the same for any other language).

    This first method is the most commonly used.

/************************************
* line of comment
* another line of comment
* yet another line of comment
************************************/

    This second method is less clear (because the individual lines are not flagged as comments).

/************************************
line of comment
another line of comment
yet another line of comment
************************************/

    This third method makes each line a separate comment. This method works best if the right column lines up vertically.

/************************************/
/* line of comment                  */
/* another line of comment          */
/* yet another line of comment      */
/************************************/

    There are two other important methods for languages (such as Java) that use the C++ approach of offering both /* */ and // comment styles.

    This method is known as the Sun commenting style and is useful with the automatic document generator that comes with the Java Development Kit.

/**
 * line of comment
 * another line of comment
 * yet another line of comment
 */

    This method is known as the Microsoft commenting style and is associated with the Visual C++ programming environment.

//////////////////////////////////////
// line of comment
// another line of comment
// yet another line of comment

other

   “Code never lies, comments sometimes do.” —Ron Jeffries

   “The proper use of comments is to compensate for our failure to express ourself in code.” —Robert C. Martin, Clean Code

   “Though programmers are often encouraged to comment their source code more thoroughly, there has been very little scientific investigation into what kinds of situations actually cause programmers to do so. I conducted a statistical study of the CVS repositories of nine Open Source projects, and made four major findings. First, the rate at which programmers comment varies widely from project to project and programmer to programmer; even the same programmer will comment at different rates on different projects. Second, programmers tend to comment larger modifications to source code more thoroughly. Third, more programmers modifying the same file does not, in general, mean more commenting. Finally, programmers tend to comment more when they are modifying code that is thoroughly commented to begin with. I then determined through an experiment with programmers that there is a causal link behind my last finding; that is, the more throughly a source code file is commented, the more thoroughly programmers will comment when they make modifications to it.” —David Marin. “What Motivates Programmers to Comment?”

   “The essence of pretty code? One can infer much about its structure from a glance, without completely reading it. I call this visual parsing: discerning the flow and relative importance of code from its shape.

• Blend In: Code changes should blend in with the original style.
• Bookish: Keep columns narrow.
• Disentangle Code Blocks: Break code into logical blocks within functions, and disentangle the purpose of separate blocks, so that each does a single thing or single kind of thing. A reader can avoid a total reading if a cursory inspection can reveal the whole block’s nature.
• Comment Code Blocks: Set off code blocks with white space and comments that describe each block. Sometimes large code blocks (with multiline comments) may embed small blocks (with single line comments). Comments should rephrase what happens in the code block, rather than be a literal translation into English. That way, even if your code is inscrutable and your comments gibberish, the reader can at least attempt to triangulate on the actual purpose. Big comments are needed for subtle or problematic code blocks, not necessarily big code blocks.
• Declutter: Reduce, reduce, reduce. Remove anything that will distract the reader.
• Make Alike Look Alike: Two or more pieces of code that do the same or similar thing should be made to look the same. Nothing speeds the reader along better than seeing a pattern.
• Overcome Indentation: The left edge of the code defines its structure, while the right side holds the detail. You must fight indentation to safeguard this property. Code that moves too quickly from left to right (and back again) mixes major control flow with minor detail.”

                     —Christopher Seiwald. “Pillars of Pretty Code”. Software Development, January 2005, pg 49-51

   “Here are some attributes of great code:

Uses the CPU efficiently (which means the code is fast) [EDITORIAL NOTE: This is no longer important until a program reaches a large scale, that is, big enough to require several servers.]

Uses memory efficiently (which means the code is small) [EDITORIAL NOTE: This is no longer important until a program reaches a large scale, that is, big enough to require several servers.]

Uses system resources efficiently

Is easy to read and maintain

Follows a consistent set of style guidelines

Uses an explicit design that follows software engineering conventions

Is easy to enhance

Is well-tested and robust (meaning that it works)

Is well-documented

                     —Randall Hyde. Write Great Code: Understanding the Machine, No Starch Press, 2004, pg. 6

   “More computing sins are committed in the name of efficiency (without necessarily achieving it) than for any other single reason - including blind stupidity.” —William A. Wulf

   “Program comments within and between modules and procedures usually convey information about the program, such as the functionality, design decisions, assumptions, declarations, algorithms, nature of input and output data, and reminder notes. Considering that the program source code may be the only way of obtaining information about a program, it is important that the programmers should accurately record useful information about these facets of the program and update them as the system changes. Common types of comments used are prologue comments and in-line comments. Prologue comments precede a program or module and describe goals. In-line comments, within the program code, describe how these goals are achieved.
   “The comments provide information that the understander can use to build a mental representation of the target program. For example, in Brooks’ top-down model, comments — which act as beacons — help the programmer not only form hypothesis, but refine them to closer representations of the program. Thus, theoretically there is a strong case for commenting programs. The importance of comments is further strengthened by evidence that the lack of good comments in programs constitutes one of the main problems that programmers encounter when maintaining programs. It has to be pointed out that comments in programs can be useful only if they provide additional information. In other words, it is the quality of the comment that is important, not its presence or absence.” —Penny Grubb and Armstrong Takang. Software Maintenance: Concepts and Practice, 2003, pg 7, 120-121

   “Software must be understandable to two different types of entities for two different purposes. First, compilers or interpreters must be able to translate source code into machine instructions. Second, people need to understand the software so they can further develop, maintain and utilize the application. The average developer overemphasizes capability and function while undervaluing the human understanding that effects improved development and continued utilization. There should be a description in clear view within the programming medium.
   “As I gradually improved my in-code documentation, I realized that English is a natural language, but computer languages, regardless of how well we use them, are still “code.” Communication via natural language is a relatively quick and efficient process. Not so with computer languages: They must be “decoded” for efficient human understanding.
   “People who read my code? wait a moment - did I say “read my code?” Now that’s a remarkable way to approach software - not to debug, analyze, program, or develop, but simply to read. The act of reading allows me to approach my code as a work of software art: I strive to make the overall design, algorithm, structure, documentation and style as simple, elegant, through and effective as practical. Yes, this takes time, but when I’m rushed, I usually dash off the wrong implementation of the wrong design, and the darn project takes twice as long as it would have had I done it right in the first place. A disciplined, focused approach clarifies my thinking and improves my implementation. In keeping with a reasonable attempt for excellence, I proofread my applications.
   “My goal is to find a balance, describing all salient program features comprehensively but concisely. I explained each software component’s purpose, the algorithm used, arguments, inputs, outputs- even the reason for #include-ing a particular header file. I document each section of each function so that the overall program flow is readily understandable.” —David Zokaities. “Writing Understandable Code”. Software Development, January 2002, pg. 48-49

   “My article seems to have generated quite a bit of controversy. The article’s text received only praise. This implies that the goal of “understandable code” is well-nigh universal. How best to achieve it seems to be a matter of highly polarized opinion. Even for the wealth of comments that I customarily provide, some readers chided me for not having enough! Other readers believe that all comments are superfluous and cause trouble by their very existence. I’ve seen horrendous maintenance problems incurred with this approach. Some readers believe that Design by Contract, coupled with lengthy function and variable names, provides all the necessary documentation.
   “My experience is that well-developed modular designs, coupled with good system documentation, descriptive identifier names and a natural-language narrative, result in code that’s a pleasure to work with and efficient to maintain.” —David Zokaities. “Feedback”. Software Development, March 2002, pg. 14

   “Documentation that is structured and contained within the program is able to immediately satisfy the changing information demands of the maintainer. Those needs are determined in part by the subtask on which he is currently working. For solving nontrivial error correction or modification problems, the maintainer must have a detailed understanding of the program. To locate a section of code, knowledge of the program’s structure is required. Knowing how an instruction sequence relates to other parts of the program is important for altering and testing software. The documentor can inform the unknowledgeable programmer in each subtask demand by varying the message content and effectively using the visual space.
   “Information may be conveyed to the maintainer in several ways. One is an abstract summary of the module at the beginning of the routine. Another is through the titles and headings of processing sections positioned in the instruction sequence. The third is in phrases and short sentences to the right of the code. They describe the processing steps and relate them to other parts of the program. The descriptions are organized into an outline that reflects the processing divisions of the routine.
   “The size and complexity of the module determine whether the information will be used. Small routines may need only comments to the right of the code. A more complete description is required for large programs.
   “The type of documentation that has just been read has a bearing on the processing of code. Documentation formats act as advance organizers of thought. Each type primes the maintainer for a different response to the instructions encountered. Messages that are consistent with the structure of the program aid recognition and recall. … Programs are documented to enhance the maintainer’s performance.” —Dennis Smith. Designing Maintainable Software. Springer-Verlag, 1999, pg. 103

   “Source code documentation is a fundamental engineering practice critical to efficient software development. Regardless of the intent of its author, all source code is eventually reused, either directly, or just through the basic need to understand it. In either case, the source code documentation acts as a specification of behavior for other engineers. Without documentation, they are forced to get the information they need by making dangerous assumptions, scrutinizing the implementation, or interrogating the author. These alternatives are unacceptable. Although some developers believe that source code “self-documents”, there is a great deal of information about code behavior that simply cannot be expressed in source code, but requires the power and flexibility of natural language to state. Consequently, source code documentation is an irreplaceable necessity, as well as an important discipline to increase development efficiency and quality.” —Jeffrey Kotula, “Source Code Documentation: An Engineering Deliverable” in Proceedings of the Technology of Object-Oriented Languages and Systems, 2000

   “Avoid decoration; for instance, keep comments brief and banner-free. Say what you want to say in the program, neatly and consistently. Then move on.” —Rob Pike, Notes on Programming in C, February 21, 1989

   “Program documentation has been propelled into importance by sheer necessity. However, it still suffers from glowing tributes but inept implementations. One of the basic elements of good program documentation is an effective program listing.” —Richard Gunderman. “A Glimpse into Program Maintenance” in Techniques of Program and System Maintenance. QED Information Sciences, 1988, pg. 59

   “In my opinion, there is nothing in the programming field more despicable than an uncommented program. A programmer can be forgiven many sins and flights of fancy, including those listed in the sections below; however no programmer, no matter how wise, no matter how experienced, no matter how hard-pressed for time, no matter how well-intentioned, should be forgiven an uncommented and undocumented program.
   “Of course, it is important to point out that comments are not an end unto themselves. As Kernighan and Plauger point out in their excellent book, The Elements of Program Style, good comments cannot substitute for bad code. However, it is not clear that good code can substitute for comments. That is, I do not agree that it is unnecessary for comments to accompany “good” code. The code obviously tells us what the program is doing, but the comments are often necessary for us to understand why the programmer has used those particular instructions.” —Edward Yourdon. “Flashes on Maintenance From Techniques of Program Structure and Design” in Techniques of Program and System Maintenance. QED Information Sciences, 1988, pg. 73

   “A program is in some sense a permanent object in that it can have a long lifetime. For the future reader, comments in a program should be truly substantive. They should say something. They should assist the program reader.
   “The professional thinks of a comment as a way to proceed from one point (a given state of knowledge) to another (understanding what is written in the program). The comment is a bridge. The professional assumes something about the reader of the program—the reader being, of course, someone else. It is fair to assume that the reader knows the language in which the program is written. The reader’s difficulty is to modify the program at hand.
   “These observations lead to some specific recommendations. First, regarding the idea of comments as a bridge—Extensive introductory program comments are entirely in order. These comments set the stage for reading the program. They may contain an outline of the solution adopted by the programmer, summarize its input and output, give a directory of key variable names, or describe an algorithm that may not be known to the reader. Such comments provide a direct bridge from the problem to the program. They do not intrude on the reading of the program itself because they appear at the beginning of the program and can be read or not as the reader desires.
   “A second recommendation has to do with procedures and other major units of the program—Introductory module comments are also in order. Comments following a procedure header explaining the general nature of the procedure are not only in order but may be necessary. Keeping in mind the bridge aspect, we need not describe the calling environment. The professional assumes that the reader has read the program to the degree that the procedure calls are understood—but maybe not the procedure itself. As such, the procedure header comments should be short and help the reader understand the next level of detail in the program.
   “Third, the professional should spend the most energy on the code itself. This means—Avoid embedded (in-line) comments within the body of the module itself. It is my view that such comments can readily intrude upon the meaning of a program. Ideally, the code should speak for itself and require few supporting comments.” —Henry Ledgard. Professional Software Volume II: Programming Practice, Addison-Wesley, 1987, pg 65

   “Common sense also leads us to the recognition of the characteristics of programs that makes the programs maintainable. Above all, we look for programs that exhibit logical simplicity — failing that, at least clarity. The earmarks of simplicity and clarity include modularity (true functional modularity, not arbitrary segmentation) and a hierarchical control structure, restrictions on each module’s access to data, structured data forms, the use of structured control forms, and generous and accurate annotation.
   “Much has been said of the technical members of this set in earlier pages. Of good annotation, there are several features that must be included. First, the header information of each procedure should provide a concise statement of the procedure’s external specifications, including a description of input and output data. Each section of the procedure should be introduced by comments identifying the section’s relation to the external characteristics. Finally, comments within each section should relate groups of statements to the program’s documented description. This last is automatically achieved by using design language statements as source code comments.” —Robert Dunn. Software Defect Removal. McGraw-Hill, 1984, pg. 308

   “71. Documentation is like term insurance: It satisfies because almost no one who subscribes to it depends on its benefits.” —Alan Perlis, Epigrams on Programming, ACM’s SIGPLAN Notices Volume 17, No. 9, September 1982, pages 7-13

---