http://www.ecst.csuchico.edu/~juliano/Teaching/Coding%20Standards.html


Dr. J's Coding Standards


  TARGET MACHINE

Unless otherwise specified, all programming assignments must be designed to compile (from scratch) and run on any of our ECC Unix servers. Code that does not meet this standard will not be graded. Additional information on Computer Science facilities is available online at http://csci.ecst.csuchico.edu/facilities ...

Students are expected to familiarize themselves with the Unix operating system. You may go to http://accounts.ecst.csuchico.edu/ to either create a new account or to update an existing account. Students must take responsibility in honing their computing skills and in gaining valuable experience functioning within both the personal computing and multi-user platforms.

During the first couple of weeks in class/lab, you will be given explicit instructions on how to submit your source code electronically. All source code connected to a programming assignment must be submitted electronically by the due date and time in order to receive ANY credit points; late submissions will not be accepted. Electronic submissions should not include any binaries (executables, object files, a.out files, core dumps, etc.). It is your responsibility to guarantee that your electronic submission is complete and includes all the necessary files to successfully compile and run/test your programs. 


  HIGH QUALITY CODE

Any submitted code must be of high quality. In particular:
  1. Code should be neat and readable, with consistent indentation and proper use of whitespace.
  2. Code should include explanatory comments, as appropriate, and these comments must be correct.
  3. Files must be organized in accordance with standard conventions.
    • In C++, split code appropriately among header and source files, and use #include in the proper places, and #ifndef to avoid multiple inclusion.
  4. Code should not perform any actions visible to the client code or the user, other than those in its specification.
    • In particular, avoid debugging printout in the turned-in version of your code.
  5. Unnecessary or duplicate code should be avoided.
    • In C++, 
      • silently written member functions should be used whenever possible. When they are used, the fact must be noted in a comment.
      • constructors should use initializers appropriately.
  6. All functions should pass their parameters and return values in appropriate ways, and be defined in the appropriate place (e.g., inside a class? outside?).
  7. Appropriate use should be made of language constructs that deny privileges.
  8. Sample source code:

  SPECIFIC STANDARDS

  1. All source code must be written in the programming language the professor requires for the class.
  2. At the beginning of every file should be a comment indicating the file’s name, author, date, and purpose.
    • Note: The purpose comment does not have to be very long. If your code is well-organized, then something like “Header for class Foo” is generally fine.
  3. Before every function definition, except possibly main, there should be comments indicating preconditions and postconditions. For a member function, you do not need to include class invariants in these lists. If a function has no preconditions (or postconditions) then write “None”.
  4. Before every class definition there must be comments indicating class invariants.
  5. Only required headers should be included, and namespace pollution should be avoided.


  CONDUCT

  1. Collaborative work of any form is strictly prohibited. Students are not allowed to seek help from any additional individual other than the Instructor of this class. You are assumed to turn in your own work and not the work of another person nor a group of people, unless otherwise specifically allowed by the Instructor.
  2. Do not cheat! Do not copy others work! Learn the material. The benefit and enjoyment you will receive will be much more valuable than any consequences of cheating. Dr. J will use electronic means to detect plagiarism/collaboration (e.g. MOSS) to check for cheaters on every assignment! Individuals who misrepresent work as being their own or who have assisted another will receive, on the first offense, a minimum penalty of a grade of zero on that assignment and a decrease of one letter grade on their final course grade. On succeeding offenses, students will get the minimum penalty of a final grade of F in the course and a memo concerning this included in their academic folder. The Dean of the student's major may also be notified with the recommendation of expulsion from the University.
  3. Dr. J reports all suspected violations of academic integrity to Student Judicial Affairs. Please refer to the University Policies and Academic Policies and Regulations, as written in the University Catalog, for more information regarding CSU Chico's Code of Student Rights and Responsibilities (CSUC EM 08-40). Students are also expected to be aware of CSU Chico's Policy on Use of Computing and Communications Technology (CSUC EM 07-01). Ignorance of these Guidelines is no excuse!


  ADDITIONAL STANDARDS

Be sure you understand what external documentation is required/expected from you. Dr. J will typically require the use of a documentation generator, a programming tool that generates documentation intended for programmers (API documentation) or end users (End-user Guide), or both, from a set of specially commented source code files, and in some cases, binary files. Here is a partial list of multi-platform, open-source documentation generators:
TOOL PROGRAMMING LANGUAGE
C/C++ IDL Java Lisp MySQL Perl PHP Python
dia2code (a utility that generates code from a Dia diagram) X   X   X   X X
DOC++ X X X          
Doxygen X X X       X X
Javadoc     X          
phpDocumentor             X  
ROBODoc X     X   X    

If external documentation is required as part of your submissions for programming assignment, then failure to include such as part of a programming assignment submission forfeits ANY chances of earning points for that assignment.