Every programming assignment will have specific criteria that your graders and instructor will use in assessing your project or homework. This will list specific functionality that your code must meet along with the points that will be awarded for meeting those objectives.
Additionally, your programs must always follow the course programming style guide given below, to the best of your ability. In some cases, you will not yet know how to implement some of these features (such as functions ....), but once have been introduced to a feature, you should incorporate it for the remainder of the term. The rubric for each subsequent assignment might not specifically mention these features - you are expected to integrate the practice without being reminded with every assignment. You will be given feedback on your program's style in Gradescope.
If your program exhibits poor style and is difficult for graders to read, you will be deducted points beyond those that are specifically mentioned in the rubric for that particular assignment. Additionally, if your program does not compile on MathLAN using the clang compiler, or it your program crashes during testing, you will be required to resubmit it
Some of the criteria given may seem overly detailed, given that you are writing small programs in response to detailed requirements given by your instructor. However, part of your learning in this course is to develop good programming habits that will carry you through to more advanced courses at Grinnell College (and beyond). I have found, for instance, that careful commenting of my own code helps me remember my thought process weeks or months later when I need to use or revise a particular program ... or part of it. It is a general principle in computer science that you don't repeat yourself (called the "DRY" principle), and you will hopefully find uses for your programs (or specific sections of them) again.
Also, if you intend to work in the software development industry, most companies will provide you with similar style guides that encapsulate the practices they require you to follow. This will be particularly true of developing good tests for your code so that it is as free of bugs as possible before it becomes integrated with the work of other people. But they may also specify how you name variables or the order of your function parameters. We won't be that specific, but keep in mind that it is much easier for your instructor and mentor to help you debug code if it is easy to read!! That includes well-named variables, short functions, and consistently indented code.
Your code must compile without errors or warnings. We will be using the clang compiler to compile your project and homework assignments for evaluation. You will lose a point for every warning that the compiler generates during grading. So be sure that your program compiles and runs on a MathLAN computer before you submit it. Do NOT expect the graders to edit your program in order to get it to run correctly and completely. If your program does not compile as submitted, it will be returned to you with a grade of 0!
Program structure does not give most students difficulty.
Generally, you should make sure that you include comments (detailed below) in your main program body and at the beginning of every function.
Keep sections of your code short. If you start realizing that you have 30+ lines of code to perform a task, you probably should break it into functions.
In C, functions generally are fairly short and do one job, returning a value to the calling program or function. Yes, functions can call other functions!! If you have a function that doesn't fit easily on your screen, it probably needs to be broken down further.
I think second most difficult aspect of coding is the writing of comments (the first, testing, is discussed below). They will seem redundant at first, and probably self explanatory, especially as you are writing small programs to comply with very specific guidelines. However, writing comments is a habit that I want to instill in you now so that they are second-nature when you start working on large, multi-file programs written with fellow students, researchers, and colleagues.
Often, comments are very valuable in reminding you why you coded a project the way that you did. And for most of the semester, you will be working with another student on projects. You are encouraged to REUSE code from project to project (giving credit to the other programmers, of course). Comments may become very important as you are trying to remember what you two did several weeks ago ... and help you integrate old functions with the new project.
I think the first trick to writing good comments is to write them before you start to code. Use comments as a sort of outline for how you will solve the problem. These comments do not have to be written in formal language. And as I code, I leave myself notes about why I wrote the code as I did rather than taking a different approach. The compiler will ignore your comments; so you can be fairly detailed without worrying about slowing down the resulting program.
When writing functions, we strongly encourage you to write "pre-conditions" and "post-conditions". Pre-conditions are comments that list your assumptions about what is true about the program and the function parameters before your function starts to run. Often, this is where you specify what values the parameters may contain. Post conditions specify what will be true about the program and the returned value ... and any values changed in the functions parameters, if you are using pointers or arrays. Yes, another programmer could read the code itself to figure this out, but if the function is complex (and this is common in C), having the pre and post conditions written down can save time and confusion.
As concrete examples, look at mortgage-good-comments.c and compare it to mortgage-poor-comments.c. The first program gives insight into what variables mean and what functions will do, but the second program merely repeats the same information found in the code.
Pay close attention to the described program input and output expectations. These are usually tied specifically to points in the rubric at the bottom of the assignment.
In general, your program should print a message at the beginning that tells the user what the program is intended to do. Yes, I know we know this .... this is practice for you to get used to communicating with your end users. Think about what you might have to output so that your roommate or a family member would know what to do with the program if you set them down in front of the computer.
Anytime you ask the user for input, you should thell them what the format should be, and what range of values is permitted.
Output is also important. In C, we can format output to make it easier to read. Use the options that you learn about for printing functions such as scanf(), and pay attention to required output formats. I will usually tell you how many decimal places are required for numbers, for instance. Follow these instructions to get full points.
Also, pay attention to the program assignment. I usually tell you want data types you should use in order to get full points for the assignment. Yes, sometimes there are other (possibly better) options, but assignments are designed to give you practice with specific skills.
In CSC 161 we are not yet too concerned with program efficiency, although there are a few things to remember:
if statements, you might use if ..... else if or consider if a switch conditional would work better. (NOTE: sometimes, you do want a group of independent if statements in order to complete the task.) One of the hardest things for new programmers to do is to test their own code. Even veteran developers can struggle with this; so it is often best to write a Test Plan before you start to any coding. Put this plan in a separate document to include when you submit your code for grading. I really like to see a checklist of what values you plan to use in testing your code and then to see you follow that in your testing transcript. You can combine the test plan and the testing transcript in one file or put them in multiple files. This is an example of a single test plan and transcript file.
1) Start by writing down the full range of expected inputs or function parameters that your program may need to handle. Make sure that you include the incorrect but plausible values that might arise, such as 0 as a divisor or negative numbers in calculating volume of an object.
2) Add to that list the specific test cases that you plan to run and how you will verify that the program is working correctly.
3) Your submission should include a transcript of program runs that test the cases you planned. Numbering these helps the grader and instructor match up your plan and how you conducted your tests.
4) Add notes to your transcript or to the test plan that indicate that you conducted the tests and that, based on the results, your program works successfully. If there is a case that the program does NOT handle correctly, it is best to be honest and point that out in this section of your submission files.