Documentation, Comments, and Coding Style Of C Programming – Online Studymaterial

basics


C code is not just functional, it is also wonderful. C code is organized, easy to read, and well documented. Organization can be achieved by separating code into useful functions and collecting functions into modules or libraries. Good organization means that at any one time, we only need to focus on a small part of a program.It would be difficult to read an essay that contained random line breaks, paragraphs were not indented, it contained different spacing or different fonts, etc.

Likewise,C code should be legible. Perfect code is consistent and makes good use of whitespace and indentation. Code within the same code block should be indented at the same level.Nested blocks should be further indented just like the outline of an essay or table of contents.
Code should also be well documented. Each line or segment of code should be clear enough that it tells the user what the code does and how it does it. This is referred to as “self-documenting” code. A person familiar with the particular language should be able to read your code and immediately understand what it does. In addition, well-written code should contain sufficient and clear comments. A comment in a program is intended for a human user to read.

      A comment is ultimately ignored by the compiler/interpreter and has no effect on the actual program. Good comments tell the user why the code was written or why it was written the way it was. Comments provide a high-level description of what a block of code, function, or program does. If the particular method or algorithm is of interest, it should also be documented.There are typically two ways to write comments. Single line comments usually begin with two forward slashes, // .Everything after the slashes until the next line is ignored.Multiline comments begin with a /* and end with a */ ; everything between them is
ignored even if it spans multiple lines. This syntax is shared among many languages including C, Java, PHP and others. Some examples



The last example above is a doc-style comment. It originated with Java, but has since been adopted by many other programming languages. Syntactically it is a normal multiline comment, but begins with a /** . Asterisks are aligned together on each line. Certain commenting systems allow you to place other marked up data inside these comments such as labeling parameters ( @param x ) or use HTML code to provide links and style. These doc-style comments are used to provide documentation for major parts of the code especially functions and data structures. Though not part of the language, other documentation tools can be used to gather the information in doc-style comments to produce formatted documentation such as web pages or Portable Document Format (PDF) documents. Comments should not be trivial: they should not explain something that should be readily apparent to an experienced user or programmer. For example, if a piece of code adds two numbers together and stores the result, there should not be a comment that explains the process. It is a simple and common enough operation that is self-evident.



However, if a function uses a particular process or algorithm such as a Fourier Transform to perform an operation, it would be appropriate to document it in a series of comments. Comments can also detail how a function or piece of code should be used. This is typically done when developing an Application Programmer Interface (API) for use by other programmers. The API’s available functions should be well documented so that users will know how and when to use a particular function. It can document the function’s expectations and behavior such as how it handles bad input or error situations.

Leave a Reply