education in computer science

 education in computer science

1.4. Syntax Rules & Pseudocode

Programming languages are a lot like human languages in that they have syntax rules.These rules dictate the appropriate arrangements of words, punctuation, and othersymbols that form valid statements in the language. For example, in many programminglanguages, commands or statements are terminated by semicolons (just as most sentencesare ended with a period). This is an example of “punctuation” in a programming language.In English paragraphs are separated by lines, in programming languages blocks of codeare separated by curly brackets. Variables are comparable to nouns and operations andfunctions are comparable to verbs. Complex documents often have footnotes that provideadditional explanations; code has comments that provide documentation and explanationfor important elements. English is read top-to-bottom, left-to-right. Programming 

languages are similar: individual executable commands are written one per line. When aprogram executes, each command executes one after the other, top-to-bottom. This isknown as sequential control flow. 

A block of code is a section of code that has been logically grouped together. Manylanguages allow you to define a block by enclosing the grouped code around opening andclosing curly brackets. Blocks can be nested within each other to form sub-blocks. 

Most languages also have reserved words and symbols that have special meaning. Forexample, many languages assign special meaning to keywords such as for , if , while ,etc. that are used to define various control structures such as conditionals and loops.Special symbols include operators such as + and * for performing basic arithmetic. 

Failure to adhere to the syntax rules of a particular language will lead to bugs andprograms that fail to compile and/or run. Natural languages such as English are veryforgiving: we can generally discern what someone is trying to say even if they speakin broken English (to a point). However, a compiler or interpreter isn’t as smart as ahuman. Even a small syntax error (an error in the source code that does not conformto the language’s rules) will cause a compiler to completely fail to understand the codeyou have written. Learning a programming language is a lot like learning a new spokenlanguage (but, fortunately a lot easier). 

In subsequent parts of this book we focus on particular languages. However, in orderto focus on concepts, we’ll avoid specific syntax rules by using pseudocode, informal,high-level descriptions of algorithms and processes. Good pseudocode makes use of plainEnglish and mathematical notation, making it more readable and abstract. A smallexample can be found in Algorithm 1.1.

Input : A collection of numbers, A = {a1, a2, . . . , an}Output : The minimal element in A1 Let min be equal to a12 foreach element ai in A do3 if ai < min then4 aiis less than the smallest element we’ve found so far5 Update min to be equal to ai6 end7 end8 output min 

Algorithm 1.1:  An example of pseudocode: finding a minimum value

1.5. Documentation, Comments, and Coding Style 

Good code is not just functional, it is also beautiful. Good code is organized, easy toread, and well documented. Organization can be achieved by separating code into usefulfunctions and collecting functions into modules or libraries. Good organization meansthat 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, paragraphswere not indented, it contained different spacing or different fonts, etc. Likewise, codeshould be legible. Well written code is consistent and makes good use of whitespaceand 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 ofcontents. 

Code should also be well documented. Each line or segment of code should be clearenough 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 ableto read your code and immediately understand what it does. In addition, well-writtencode should contain sufficient and clear comments. A comment in a program is intendedfor a human user to read. A comment is ultimately ignored by the compiler/interpreterand has no effect on the actual program. Good comments tell the user why the code waswritten or why it was written the way it was. Comments provide a high-level descriptionof what a block of code, function, or program does. If the particular method or algorithmis of interest, it should also be documented. 

There are typically two ways to write comments. Single line comments usually beginwith two forward slashes, // .1 Everything after the slashes until the next line is ignored.Multiline comments begin with a /* and end with a */ ; everything between them isignored even if it spans multiple lines. This syntax is shared among many languagesincluding C, Java, PHP and others. Some examples: 

The last example above is a doc-style comment. It originated with Java, but has sincebeen adopted by many other programming languages. Syntactically it is a normalmultiline comment, but begins with a /** . Asterisks are aligned together on eachline. Certain commenting systems allow you to place other marked up data inside thesecomments such as labeling parameters ( @param x ) or use HTML code to provide linksand style. These doc-style comments are used to provide documentation for major partsof 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 commentsto 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 bereadily apparent to an experienced user or programmer. For example, if a piece of codeadds two numbers together and stores the result, there should not be a comment thatexplains 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 Transformto 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 istypically done when developing an Application Programmer Interface (API) for useby other programmers. The API’s available functions should be well documented sothat users will know how and when to use a particular function. It can document thefunction’s expectations and behavior such as how it handles bad input or error situations.