Table of Contents

iii

Table of Contents
Table of Contents ........................................................................................................................... iii Introduction ..................................................................................................................................... v What you are about to read: ........................................................................................................ v Who this manual is for: ............................................................................................................... v Purpose of this manual: ............................................................................................................... v Headings ......................................................................................................................................... 3 Contents of a heading.................................................................................................................. 3 Heading Format .......................................................................................................................... 4 Lines ................................................................................................................................................ 7 Line Limit ................................................................................................................................... 7 Line Transitions .......................................................................................................................... 8 Text strings.............................................................................................................................. 8 All others................................................................................................................................. 8 Comments ..................................................................................................................................... 11 Whitespace .................................................................................................................................... 15 Why use whitespace? ................................................................................................................ 15 When to use whitespace ............................................................................................................ 16 Alignment and Indentation ........................................................................................................... 19 Indent Style ............................................................................................................................... 19 Vertical Alignment.................................................................................................................... 20 Variable Names ............................................................................................................................. 25 Good Variable Names ............................................................................................................... 25 Capitalization ............................................................................................................................ 25 Index ............................................................................................................................................. 27

Introduction

Introduction
What you are about to read:
The following text is a manual or general guideline for proper programming code formatting. These are the standards expected by the vast majority of professors at UNT and in the work force.

Who this manual is for:

This is a manual for any student currently enrolled in, or planning to enroll in a computer science class. Students taking any class ranging from entry level to senior level material will find this manual useful. The following guide could also be helpful for those already in the work force who need a reminder on code formatting. This manual is not for a user that has no experience with computer languages and has no plans to do so in the future. Without a understanding of computer languages the following text will make no sense.

Purpose of this manual:

The following manual was written with the sole purpose of helping students succeed in the classroom and workforce when programming. Students will find useful information on the standards expected of them when coding, and professors will have easier grading when all students are following a uniformed guideline.

Chapter One

Headings
Contents of a heading
The content of a heading should look like the figure below:

The entire heading is commented out of the program using the /**, *, and **/ commands. The use of whitespace is important here, as a big block of text is much harder to read than well formatted writing. The first line of the heading should be the file name, or where the user can locate this source code in the future. The file name should represent the type of file it contains. In a program with multiple files it is important to identify the main method in that files name. The second line of the heading should contain the name of the program, the name should give the user some indication of what the program is designed to do. As in the example the program converts text to Morse Code. Line three is the coder, or the name of the individual, or group of individuals that wrote the code in the file. This, as all parts of the heading is extremely important, so that anyone using of editing the code in the future knows who to contact if they need assistance. The last line is the version and complier used to test and run the program during coding. Not all compilers will run the program the same, and a future user may need to know what you used to make it work best.

Computer Programming:Format Standards

Heading Format
When formatting the heading it is important to use whitespace, indentation, and vertical alignment. Information about all of these coding principles can be found later in this manual; however they are used in this section of your code. Important! Never forget to include your name in the heading, how else will you get credit for your work!

Chapter Two

Lines
Line Limit
There is a limit to the number of characters that should be typed on any given line. While in some cases this may seem a bit strange and counterproductive, when you get to a point where you have to start reading and debugging code or worse someone else code you will definitely appreciate the limit. For most Java and C++ programs this limit will be 81 characters. When using any other coding language that you are unfamiliar with 81 characters is usually always a safe bet.

Notice the line on the screenshot above. This line is the line limit for the code. If your code passes this line you should loop it to the next line as shown in line transitions on the next page.

Tip When printing code, any code extending passed the limit is likely to not print.

Computer Programming:Format Standards

Line Transitions
Text strings For text strings you would do as I have done in the picture below. Simply break off the text with a quotation mark, then add a + either on that line or the next one, reopen your quotation marks and continue the string, repeat as needed.

Just be very careful not to forget to include a space inside of the quotations either at the end of the line, or the beginning of the next, otherwise the two words will combine. All others For all other lines, simply hit the return key when you have reached the line limit and continue typing, as shown below.

Did you catch the mistake? In the figure above there is a comma that extends passed the line limit!

Chapter Three

11

Comments
Comments are one of the single most important parts of a program. Now at first that may seem very confusing, but it could not be truer. It is very important to comment everywhere in your code telling other coders exactly what you were doing where and why. In the workforce you may be put in a group with 20+ other coders on a single project. At some point all of your work has to come together to create the collaborative final program. If one person leaves out comments on their code and its unclear what was being done or why, combing that code with one much less twenty other pieces proves to be quite a daunting task. I sometimes, in large projects, even forget what I was doing five plus pages up in my code when trying to add or debug code. Comments make everything much easier and smoother for you, and your team. Example:

13

Chapter four

15

Whitespace
Why use whitespace?
Whitespace is the simplest way to make your code look professional and easy to read. Think of coding like typing an essay. Edgar Allen Poe himself could write the most brilliant short story the world has ever seen; however, if it is no formatted and just looks like a giant wall of text, who is going to read it? The computer does not care about formatting, you can take every black space and line out of code and it will still run just as it did with great formatting. As I am sure you can imagine reading and entire program that looks like:

Is exponentially easier than this, even though when sent through the compiler the code runs the same.

16

Computer Programming:Format Standards

When to use whitespace

Refer to the pictures on the previous page for a visual guide of whitespace. Whitespace consist of spaces and blank lines in order to make the page easier to read. A general rule, if youre in doubt use whitespace, its free and takes up absolutely no storage space in your program. Its always better to have extra whitespace than it is to be missing it. Whitespace is free! Whitespace in a programs code does not take up any memory in the program.

17

Chapter five

19

Alignment and Indentation

Indent Style
Indent styles assist in identifying control flow and blocks of code. In some programming languages indentation is used to delimit logical blocks of code; correct indentation in these cases is more than a matter of style. In other languages indentation and white space do not affect function, although logical and consistent indentation makes code more readable. Compare: if (hours < 24 && minutes < 60 && seconds < 60) { return true; } else { return false; } or if (hours < 24 && minutes < 60 && seconds < 60) { return true; } else { return false; } with something like if ( hours < 24 && minutes < 60 && seconds < 60 ) {return true ;} else {return false ;} The first two examples are probably much easier to read because they are indented in an established way (a "hanging paragraph" style). This indentation style is especially useful when dealing with multiple nested constructs.

20

Computer Programming:Format Standards

Vertical Alignment
It is often helpful to align similar elements vertically, to make typo-generated bugs more obvious. Compare: $search = array('a', 'b', 'c', 'd', 'e'); $replacement = array('foo', 'bar', 'baz', 'quux'); // Another example: $value = 0; $anothervalue = 1; $yetanothervalue = 2; with: $search = array('a', 'b', 'c', 'd', 'e'); $replacement = array('foo', 'bar', 'baz', 'quux'); // Another example: $value = 0; $anothervalue = 1; $yetanothervalue = 2; The latter example makes two things intuitively clear that were not clear in the former:

the search and replace terms are related and match up: they are not discrete variables; there is one more search term than there are replacement terms. If this is a bug, it is now more likely to be spotted.

However, note that there are many arguments against vertical alignment:

Inter-line false dependencies; tabular formatting creates dependencies across lines. For example, if an identifier with a long name is added to a tabular layout, the column width may have to be increased to accommodate it. This forces a bigger change to the source code than necessary, and the essential change may be lost in the noise. This is detrimental to Revision control where inspecting differences between versions is essential. Brittleness; if a programmer does not neatly format the table when making a change, maybe legitimately with the previous point in mind, the result becomes a mess that deteriorates with further such changes. Simple refactoring operations, such as search-and-replace, may also break the formatting.

Chapter five

21

Resistance to change; tabular formatting requires more effort to maintain. This may put off a programmer from making a beneficial change, such as adding, correcting or improving the name of an identifier, because it will mess up the formatting. Reliance on mono-spaced font; tabular formatting assumes that the editor uses a fixedwidth font. Many modern code editors support proportional fonts, and the programmer may prefer to use a proportional font for readability. Tool dependence; some of the effort of maintaining alignment can be alleviated by tools (e.g. a source code editor that supports elastic tabstops), although that creates a reliance on such tools.

For example, if a simple refactoring operation is performed on the code above, renaming variables "$replacement" to "$r" and "$anothervalue" to "$a", the resulting code will look like this: $search = array('a', 'b', 'c', 'd', 'e'); $r = array('foo', 'bar', 'baz', 'quux'); // Another example: $value = 0; $a = 1; $yetanothervalue = 2; The original sequential formatting will still look fine after such change: $search = array('a', 'b', 'c', 'd', 'e'); $r = array('foo', 'bar', 'baz', 'quux'); // Another example: $value = 0; $a = 1; $yetanothervalue = 2;

23

Chapter Six

25

Variable Names
Good Variable Names
Another key concept to follow in order to make coding much easier for you and your team is proper naming of variables. A poor example of a variable name would be num or one these names give absolutely no indication as to what they actually do. A good variable name gives a good description of what it is doing, while staying relatively short and all variable names must be one continuous string. Some examples forLoopCounterOne or finalOutput with names like these we know exactly what they are doing without having to search for them.

Capitalization
Due to the fact that all variable names must be one continuous sting of characters it is important to capitalize the first character of every word, making it clear what the name is. Make debugging a breeze! Good variable names make it much easier to back track your code.

Index

27

Index
C
C++ 7 Comments iii, 11 complier 3 computer v, 15 computer science v

N
nested 19

P
program 3, 11, 15, 16 programming v, 19

F
files 3 formatted 3, 15

S
string 8, 25

H
heading iii, 3, 4

T
text strings 8

I
indentation 4, 19

V
variable variable names 25 Variable 25 vertical alignment 4

J
Java 7

L
languages v, 19 limit 7, 8 line transitions 7

W
whitespace 3, 4, 15, 16 workforce v, 11