CSCI-345/780 Coding Guidelines

Introduction

All code that you submit for this course must be easy for me to read! That means it must be laid out on the page so I can see the structure of the code easily, don't have to scroll horizontally to read anything, and that there are comments to help me find the significant parts of the code in each file.

It also means that your comments should be "just enough, not too much." That is, you do not need to document the obvious and should assume that your reader knows the Handel-C language. Nor do you need to demonstrate to me that you know what you are doing. I will be able to tell that by how clean your code is and how well it runs.

Think of documentation as what professionals do when they write code so that others can maintain it after they have moved on, and you will have the right idea for dealing with this issue for this course.

Guidelines

Here are some rules for how to document your code. They are not hard and fast, but they should give you some ideas of how to achieve the goals outlined above.

Set your editor to substitute spaces for tab characters. In DK, you do this from Tools -> Options -> Tabs. Doing this makes sure that your code indentation will look right no matter what program settings I use when I read it.
No line of code, including comments, may extend beyond column 80. This is not always practical, but it is a good general rule for preventing horizontal scrolling. I have a program that tells me exactly how many tab characters and long lines there are in your source files, so watch out!
Put the name of each source file in a comment in the first line of the file. Sure, the file name is normally in a title bar somewhere, but putting it at the beginning of a file helps the reader keep track of what he or she is looking at.
Put a comment block at the beginning of each source file telling what the program does, who the author(s) is(are), and when the program was written. This is a matter of professionalism. But it helps readers navigate through projects with multiple modules more easily, so it serves a very practical purpose too.
Put a comment block before each function, macro proc definition, and endless loop. Make sure this comment block stands out on the page. For example, put a horizontal line below the name of the function or macro proc name, such as the following:
Sample comment block for a function or macro proc
```
    //  main()
    //  -------------------------------------------------------------
    /*
     *    Description of what the function does goes here.
     */
      void main(void) ...
      
```
This is another case of helping the reader navigate through the source code efficiently.
Be sure there is at least one space between comment leaders and the text that follows. (“Comment leaders” are // for single line comments, or /* or * for comment blocks.) Format the comments so they are easy to read and document the logical structure of the code.
Put spaces around operators to make the code easier to read. “x += 3;” is easier to read than “x+=3;”
Be sure all code compiles and builds with no errors or warnings for both Debug and EDIF configurations. The only exceptions are the Pal macro expansion warnings (“possible infinite expansion”) that do not indicate a problem.
Be sure the Xilinx tools report no problems, such as an inability to meet timing constraints